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
This project’s goal is the creation of real JavaDoc for Scala projects. While ScalaDoc—the native API documentation format of Scala—has several benefits over JavaDoc, Java programmers are very much used to having access to API documentation in a syntax matching their programming language of choice. Another motivating factor may be that javadoc-JARs are supported within IDE, e.g. showing tooltip help texts.
5
+
This project’s goal is the creation of real Javadoc for Scala projects. While Scaladoc—the native API documentation format of Scala—has several benefits over Javadoc, Java programmers are very much used to having access to API documentation in a syntax matching their programming language of choice. Another motivating factor may be that javadoc-JARs are supported within IDE, e.g. showing tooltip help texts.
6
6
7
7
## How to Use It
8
8
9
-
GenJavaDoc is a Scala compiler plugin which emits structurally equivalent Java code for all Scala sources of a project, keeping the ScalaDoc comments (with a few format adaptions). Integration into an SBT build is quite simple:
9
+
GenJavadoc is a Scala compiler plugin which emits structurally equivalent Java code for all Scala sources of a project, keeping the Scaladoc comments (with a few format adaptions). Integration into an SBT build is quite simple:
Adding `javadocSettings` to a `Project` this way will replace the
36
-
packaging of the API docs to use the JavaDoc instead of the ScalaDoc
37
-
(i.e. the `XY-javadoc.jar` will then contain JavaDoc). The ScalaDoc
36
+
packaging of the API docs to use the Javadoc instead of the Scaladoc
37
+
(i.e. the `XY-javadoc.jar` will then contain Javadoc). The Scaladoc
38
38
can still be generated using the normal `doc` task, whereas the
39
-
JavaDoc can now be generated using `genjavadoc:doc`.
39
+
Javadoc can now be generated using `genjavadoc:doc`.
40
40
41
-
GenJavaDoc can also be integrated into a Maven build (inspired by [this answer on StackOverflow](http://stackoverflow.com/questions/12301620/how-to-generate-an-aggregated-scaladoc-for-a-maven-site/16288487#16288487)):
41
+
GenJavadoc can also be integrated into a Maven build (inspired by [this answer on StackOverflow](http://stackoverflow.com/questions/12301620/how-to-generate-an-aggregated-scaladoc-for-a-maven-site/16288487#16288487)):
42
42
43
43
~~~xml
44
44
<profile>
@@ -103,9 +103,9 @@ GenJavaDoc can also be integrated into a Maven build (inspired by [this answer o
103
103
</profile>
104
104
~~~
105
105
106
-
### Translation of ScalaDoc comments
106
+
### Translation of Scaladoc comments
107
107
108
-
Comments found within the Scala sources are transferred to the corresponding Java sources including some modifications. These are necessary since ScalaDoc supports different mark-up elements than JavaDoc. The modifications are:
108
+
Comments found within the Scala sources are transferred to the corresponding Java sources including some modifications. These are necessary since Scaladoc supports different mark-up elements than Javadoc. The modifications are:
109
109
110
110
*`{{{ ... }}}` is translated to `<pre><code> ... </code></pre>`, where within the pre-formatted text the following are represented by their HTML entities: `@`, `<`, `>`
111
111
* typographic quotes (double as well as single) are translated to `”` and friends
@@ -116,30 +116,30 @@ Comments found within the Scala sources are transferred to the corresponding Jav
116
116
117
117
### Additional transformations
118
118
119
-
Some additional transformations are applied in order to make the generated JavaDoc more useful:
119
+
Some additional transformations are applied in order to make the generated Javadoc more useful:
120
120
121
-
* if a Scala method or class was marked `@scala.annotation.deprecated` an equivalent JavaDoc`@deprecated` comment line will be inserted to the resulting JavaDoc comment.
121
+
* if a Scala method or class was marked `@scala.annotation.deprecated` an equivalent Javadoc`@deprecated` comment line will be inserted to the resulting Javadoc comment.
122
122
123
123
## How it Works
124
124
125
-
ScalaDoc generation is done by a special variant of the Scala compiler, which can in principle emit different output, but the syntax parsed by the ScalaDoc code is the Scala one: the compiler phases which adapt the AST to be more Java-like (to emit JVM byte-code in the end) are not run. On the other hand source comments cannot easily be associated with method signatures parsed from class files, and generating corresponding Java code to be fed into the `javadoc` tool is also no small task.
125
+
Scaladoc generation is done by a special variant of the Scala compiler, which can in principle emit different output, but the syntax parsed by the Scaladoc code is the Scala one: the compiler phases which adapt the AST to be more Java-like (to emit JVM byte-code in the end) are not run. On the other hand source comments cannot easily be associated with method signatures parsed from class files, and generating corresponding Java code to be fed into the `javadoc` tool is also no small task.
126
126
127
-
The approach taken here is to use the Scala compiler’s support as far as possible and then generate mostly valid Java code corresponding to the AST—but only the class and method structur without implementations. Since the JavaDoc shall contain generic type information, and shall also not be confused by artifacts of Scala’s encoding of traits and other things, the AST must be inspected before the “erasure” phase; due to Java’s flat method parameter lists the other bound on where to hook into the transformation is that it should be after the “uncurry” phase (which transforms `def f(x: Int)(s: String)` into `def f(x: int, s: String)`). Luckily there is a gap between those two phases which is just wide enough to squeeze some code in.
127
+
The approach taken here is to use the Scala compiler’s support as far as possible and then generate mostly valid Java code corresponding to the AST—but only the class and method structur without implementations. Since the Javadoc shall contain generic type information, and shall also not be confused by artifacts of Scala’s encoding of traits and other things, the AST must be inspected before the “erasure” phase; due to Java’s flat method parameter lists the other bound on where to hook into the transformation is that it should be after the “uncurry” phase (which transforms `def f(x: Int)(s: String)` into `def f(x: int, s: String)`). Luckily there is a gap between those two phases which is just wide enough to squeeze some code in.
128
128
129
129
One drawback of this choice is that the flattening of classes and companion objects or the mixing-in of method implementations from traits into derived classes happens much later in the transformation pipeline, meaning that the compiler plugin has to do that transformation itself; for this it has the advantage that it does not need to be 100% Scala-correct since the goal is just to document method signatures, not to implement all the intricacies of access widening and so on.
130
130
131
131
## Known Limitations
132
132
133
-
* Many ScalaDoc tags and features are simply not supported by the javadoc tool and genjavadoc does not reimplement them:
133
+
* Many Scaladoc tags and features are simply not supported by the javadoc tool and genjavadoc does not reimplement them:
134
134
135
-
*`@note`, `@example`, `@group` etc. do not work and are errors in JavaDoc 8, so they cannot be used
135
+
*`@note`, `@example`, `@group` etc. do not work and are errors in Javadoc 8, so they cannot be used
136
136
* links to methods that use the overload disambiguation syntax will not work
137
137
138
-
* Classes and objects nested inside nested objects are emitted by Scalac in such a form that there is no valid Java syntax to produce the same binary names. This is due to differences in name mangling (where javac inserts more dollar signs than scalac does). This means that while JavaDoc is generated for these (in order to guarantee that JavaDoc will find all the types it needs) the precise names are neither correct nor usable in practice.
138
+
* Classes and objects nested inside nested objects are emitted by Scalac in such a form that there is no valid Java syntax to produce the same binary names. This is due to differences in name mangling (where javac inserts more dollar signs than scalac does). This means that while Javadoc is generated for these (in order to guarantee that Javadoc will find all the types it needs) the precise names are neither correct nor usable in practice.
139
139
140
140
## Reporting Bugs
141
141
142
-
If you find errors in the generation process or have suggestions on how to improve the quality of the emitted JavaDoc contents, please report issues on this GitHub repo’s issue tracker.
142
+
If you find errors in the generation process or have suggestions on how to improve the quality of the emitted Javadoc contents, please report issues on this GitHub repo’s issue tracker.
0 commit comments