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: scala3doc/README.md
+33-46Lines changed: 33 additions & 46 deletions
Original file line number
Diff line number
Diff line change
@@ -20,8 +20,8 @@ We're aiming to support all the features Scaladoc did, plus new and exciting one
20
20
Use the following commands to generate documentation for this project and for Dotty, respectively:
21
21
22
22
```
23
-
sbt generateSelfDocumentation
24
-
sbt generateDottyLibDocumentation
23
+
sbt scala3doc/generateSelfDocumentation
24
+
sbt scala3doc/generateScala3Documentation
25
25
```
26
26
27
27
To actually view the documentation, the easiest way is to run the following in project root:
@@ -41,15 +41,16 @@ the documentation won't work completely if you don't.
41
41
## CLI Documentation
42
42
43
43
CLI command for running our tool is in form: `sbt main -n <name> -o <output> -t <tasty-files> -cp <classpath> -s { <sources> } -d <documentation> ` where:
44
-
-`<name>`: name of module in generated documentation
45
-
-`<output>`: location where documentation should be created
46
-
-`<tasty-files>`: is list of dirs or jars that contains tasty files that should be documented
47
-
-`<classpath>`: classpath that was used to generate tasty files
48
-
-`<sources>`: links to source files of module that are used to link symbols on pages to their source file. They need to be supplied in form:
49
-
`local_dir=remote_dir#line_suffix` e.g. `src/main/scala=https://github.com/lampepfl/scala3doc/tree/master/src/main/scala#L`
50
-
-`<documentation>`: directory of static documentation that you would like to render with API documentation. This feature is provided by dokka-site plugin:
-`<name>`: name of module in generated documentation
46
+
-`<output>`: location where documentation should be created
47
+
-`<tasty-files>`: is list of dirs or jars that contains tasty files that should be documented
48
+
-`<classpath>`: classpath that was used to generate tasty files
49
+
-`<sources>`: links to source files of module that are used to link symbols on pages to their source file. They need to be supplied in form:
50
+
`local_dir=remote_dir#line_suffix` e.g. `src/main/scala=https://github.com/lampepfl/scala3doc/tree/master/src/main/scala#L`
51
+
-`<documentation>`: directory of static documentation that you would like to render with API documentation. This feature is provided by dokka-site plugin:
To implement integration tests that inspects state of the model on different stages of
76
-
documentation generation one can use [ScaladocTest](src/test/scala/dotty/dokka/ScaladocTest.scala#L15).
77
-
This class requires providing the name of the test and a the list of assertions.
78
-
79
-
Name of the test is used to extract symbols that should be included in given test run from
80
-
the TASTY files. All test data is located in [scala3doc-testcases module](../scala3doc-testcases/src).
81
-
It is compiled together with the rest of modules. This solves lots of potential problems with
82
-
invoking the compiler in a separate process such as mismatching versions. Every test is using
83
-
only symbols defined in the package with the same name as the test located inside top level `tests`
84
-
package (including subpackages). This restriction may be relaxed in the future.
85
-
86
-
Assertions of each test are defined as list of [Assertion enum](src/test/scala/dotty/dokka/ScaladocTest.scala#L63)
87
-
instances. Each of them represents a callback that is invoked in corresponding phase of
88
-
documentation generation. Those callback can inspect the model, log information and raise errors
89
-
using `reportError` method.
90
-
91
-
#### Signature tests
76
+
Most tests rely on comparing signatures (of classes, methods, objects etc.) extracted from the generated documentation
77
+
to signatures found in source files. Such tests are defined using [MultipleFileTest](test/dotty/dokka/MultipleFileTest.scala) class
78
+
and its subtypes (such as [SingleFileTest](test/dotty/dokka/SingleFileTest.scala))
92
79
93
-
Some of the tests rely on comparing signatures (of classes, methods, objects etc.) extracted from
94
-
the generated documentation to signatures found in source files. Such tests are defined using
95
-
[SignatureTest](src/test/scala/dotty/dokka/SignatureTest.scala#L16) class, that is a subclass of
96
-
`ScaladocTest` and uses exactly tha same mechanism to find input symbols in the TASTY files.
80
+
WARNING: As the classes mentioned above are likely to evolve, the description below might easily get out of date.
81
+
In case of any discrepancies rely on the source files instead.
97
82
98
-
Signature tests by default assume that sources that were used to generate used TASTY files are
99
-
located in the file with the same name as the name of the test. If this is not the case optional
100
-
parameter `sourceFiles` can be used to pass list of source file names (without `.scala` extension).
101
-
102
-
Those tests also requires specifying kinds of ignatures from source files (corresponding to
103
-
keywords used to declare them like `def`, `class`, `object` etc.) whose presence in the generated
104
-
documentation will be checked (other signatures, when missing, will be ignored).
83
+
`MultipleFileTest` requires that you specify the names of the files used to extract signatures,
84
+
the names of directories containing corresponding TASTY files
85
+
and the kinds of signatures from source files (corresponding to keywords used to declare them like `def`, `class`, `object` etc.)
86
+
whose presence in the generated documentation will be checked (other signatures, when missing, will be ignored).
87
+
The mentioned source files should be located directly inside `src/main/scala/tests` directory
88
+
but the file names passed as parameters should contain neither this path prefix nor `.scala` suffix.
89
+
The TASTY folders are expected to be located in `target/${dottyVersion}/classes/tests` (after successful compilation of the project)
90
+
and similarly only their names relative to this path should be provided as tests' parameters.
91
+
For `SingleFileTest` the name of the source file and the TASTY folder are expected to be the same.
105
92
106
93
By default it's expected that all signatures from the source files will be present in the documentation
107
94
but not vice versa (because the documentation can contain also inherited signatures).
@@ -129,7 +116,6 @@ instead of
129
116
def foo(): Int
130
117
```
131
118
132
-
133
119
Because of the way how signatures in source are parsed, they're expected to span until the end of a line (including comments except those special ones mentioned above, which change the behaviour of tests) so if a definition contains an implementation, it should be placed in a separate line, e.g.
134
120
135
121
```
@@ -150,8 +136,9 @@ Otherwise the implementation would be treated as a part of the signature.
150
136
1. Replace Dottydoc as the dedicated tool for documenting Dotty code
151
137
152
138
This includes:
153
-
+ supporting Dotty's doc pages
154
-
+ releasing together with Dotty as the dedicated documentation tool
139
+
140
+
- supporting Dotty's doc pages
141
+
- releasing together with Dotty as the dedicated documentation tool
155
142
156
143
1. Support all kinds of Dotty definition and generate documentation for the
0 commit comments