You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: scala3/scaladoc.md
+76-16Lines changed: 76 additions & 16 deletions
Original file line number
Diff line number
Diff line change
@@ -7,9 +7,9 @@ The new Scala version 3 comes with a completely new implementation of the docume
7
7
In this article you can find highlights of new features that are or will be introduced to Scaladoc.
8
8
For general reference, visit [Scaladoc manual](https://dotty.epfl.ch/docs/usage/scaladoc/)
9
9
10
-
##New features
10
+
# New features
11
11
12
-
###Markdown syntax
12
+
## Markdown syntax
13
13
14
14
The biggest change introduced in the new version of Scaladoc is the change of the default language for docstrings. So far Scaladoc only supported Wikidoc syntax.
15
15
The new Scaladoc can still parse legacy `Wikidoc` syntax, however Markdown has been chosen as a primary language for formatting comments.
@@ -18,7 +18,7 @@ To switch back to `Wikidoc` one can pass a global flag before running the `doc`
18
18
For more information on how to use the full power of docstings, check out [Scaladoc docstrings][scaladoc-docstrings]
19
19
20
20
21
-
###Static site
21
+
## Static site
22
22
23
23
Scaladoc also provides an easy way for creating **static sites** for both documentation and blog posts in the similar way as Jekyll does.
24
24
Thanks to this feature, you can store your documentation along-side with the generated Scaladoc API in a very convenient way.
@@ -27,23 +27,23 @@ For more information on how to configure the generation of static sites check ou
Blog posts are a specific type of static sites. In the Scaladoc manual you can find additional information about how to work with [blog posts][built-in-blog].
The following features are currently (May 2021) not stable to be released with scaladoc, however we are happy to hear your feedback. Each feature has its own thread at scala-lang contributors site, where you can share your opinions.
45
45
46
-
###Snippets compiler
46
+
## Snippets compiler
47
47
48
48
One of the experimental features of Scaladoc will be a snippets compiler. This tool will allow you to compile snippets that you attach to your docstring
49
49
to check that they actually behave as intended, e. g. compile or throw some exception. The feature is very similar to `tut` or `mdoc` tools,
@@ -54,26 +54,86 @@ For more information you can follow this [thread](https://contributors.scala-lan
Haskell programmers are probably familiar with Hoogle - a documentation search engine that allows you to find functions by their signatures rather than their symbolic names. Since many Scala developers are also functional programming fans, we decided to add a similar functionality to Scaladoc.
59
+
Haskell programmers are probably familiar with [Hoogle](https://hoogle.haskell.org/) - a documentation search engine that allows you to find functions by their signatures rather than their symbolic names. Since many Scala developers are also functional programming fans, we decided to add a similar functionality to Scaladoc.
60
60
61
61
To use this feature simply type the signature of the function You are looking for in scaladoc searchbar. This is how it works:
For this feature to work scaladoc uses [Inkuire](https://github.com/VirtusLab/Inkuire) search engine, which was designed to work for Kotlin and is being currently adapted to work for Scala 3.
65
+
This feature is provided by [Inkuire](https://github.com/VirtusLab/Inkuire) search engine, which works for Scala 3 and Kotlin. To be up-to-date with development of this feature follow [Inkuire repository](https://github.com/VirtusLab/Inkuire)for new releases.
66
66
67
-
To be up-to-date with this feature You can follow this [scala contributors thread](https://contributors.scala-lang.org/t/pre-sip-scaladoc-search-by-type-signature/1604/15) or follow [Inkuire](https://github.com/VirtusLab/Inkuire) directly for new releases.
67
+
Note that this feature is still in development, so it can be subject to considerable change.
68
+
If You encounter a bug or have an idea for improvement don't hesitate to create an issue on [Inkuire](https://github.com/VirtusLab/Inkuire/issues/new) or [dotty](https://github.com/lampepfl/dotty/issues/new).
68
69
69
-
Note that this feature is still in development.
70
-
Some features that we are still working on:
70
+
### How it works
71
+
72
+
Using this feature allows to find `def`s and `val`s from the documented code.
73
+
74
+
In order for a scaladoc searchbar query to be searched using Inkuire instead of the default search engine, the query has to contain `=>` character sequence.
75
+
76
+
Accepted input is similar to a curried function signature in Scala 3. With some differences:
77
+
- AndTypes, OrTypes and Functions have to be enclosed in parentheses e.g. `(Int & Any) => String`
78
+
- Transformations without any input can be found by a syntactic by name call e.g. `=> Int`
79
+
- A wildcard `_` can be used to indicate that we want to match any type in a given place e.g. `Long => Double => _`
80
+
- Types in the form of single letter e.g. `A` or a letter with a digit `X1` are automatically assumed to be type variables
81
+
- Other type variables can be declared just like in polymorphic functions e.g. `[A, B] => A => B => A`
82
+
83
+
Some examples to give You a better idea:
84
+
-`List[Int] => (Int => Long) => List[Long]`
85
+
-`(A, B) => A`
86
+
-`Set[Long] => Long => Boolean`
87
+
-`Int => Long => Int`
88
+
-`String => Int => Char`
89
+
-`(Int & Float) => (String | Double)`
90
+
91
+
Inkuire works as a JavaScript worker in the browser thanks to the power of [ScalaJS](https://www.scala-js.org/).
92
+
93
+
To enable Inkuire when running scaladoc add flag `-Ygenerate-inkuire`. By adding this flag two files are generated:
94
+
-`inkuire-db.json` - this is the file containing all searchable declarations from the currently documented project in a format readable to Inkuire search engine.
95
+
-`inkuire-config.json` - this file contains locations of database files that should be searchable from documentation of the current project. By default it will be generated with the location of the local db file as well as default implied locations of detabase files in `External mappings`.
96
+
97
+
When it comes to how the code is mapped to InkuireDb entries, there are some transformations to make the engine more opinionated(though open to suggestions and changes). Firstly the receiver(non-module owner) of a function can be treated as a first argument. Automatic currying is also applied, so that the results aren't dependant on argument lists. When finding matches `val`s and `def`s are not distinguished.
98
+
99
+
So the following declarations should be found by query `Int => Int => Int => Int`:
100
+
```
101
+
class Num:
102
+
def a(i: Int, j: Int): Int
103
+
def b(i: Int)(j: Int): Int
104
+
def c(i: Int): (Int => Int)
105
+
val d: Int => Int => Int
106
+
val e: Int => Int => Int
107
+
val f: (Int, Int) => Int
108
+
end Num
109
+
110
+
def g(i: Num, j: Int, k: Int): Int
111
+
extension (i: Num) def h(j: Int, k: Int): Int
112
+
def i(i: Num, j: Int)(k: Int): Int
113
+
extension (i: Num) def j(j: Int)(k: Int): Int
114
+
...
115
+
```
116
+
117
+
When it comes to type aliases, they are desugared on both the declaration and the query signature. This means that for declarations:
118
+
```
119
+
type Name = String
120
+
121
+
def fromName(name: Name): String
122
+
def fromString(str: String): Name
123
+
```
124
+
both functions (`fromName` and `fromString`) should be found for queries `Name => Name`, `String => String`, `Name => String` and `String => Name`.
125
+
126
+
The edges are the roughest with implicits/givens.
127
+
Implicit conversions are only applied once and only to the receiver/first argument. Since allowing for more than one applicationof implicit conversions poses problems like for example infinite applications of implicit conversions.
128
+
Implicit arguments are ignored at the moment, but we are very much planning on better support for them in near future.
129
+
130
+
Some other things we are still working on:
71
131
- Generating type information (InkuireDB) for Java sources
72
132
- More advanced type level constructs like e.g. explicit type bounds and repeated types
73
-
- Managing dependencies using scaladoc external mappings
133
+
- Better managing of dependencies using scaladoc external mappings
134
+
- Integration with [Metals](https://scalameta.org/metals/)
0 commit comments