Doclet for Java 9+

[eomeara]

Spring Boot 2.0.2, Gradle 4.8, Spring Auto RestDocs 2.0.1, macOS 10.13.5, JDK 10.0.1-zulu, SDKMAN 5.6.4+305.

It appears that the build is not using the standard doclet (from Oracle) and hence the -d option is not supported. Some of the gradle error output is shown below. Note that the output for running javadoc --help at the command line follows the error output and indicates that the javadoc command does support the oracle standard doclet under some conditions, but not with Auto Rest Docs. On reviewing jdk 10 it appears the standard doclet is not supported programatically. Note options.doclet in part of build.gradle below. Also note destinationDir. Perhaps there should be a jdk9+ version that does not use the com.sun namespace which was deprecated in jdk9 and partly removed in jdk10.

Part of build.gradle

task jsonDoclet(type: Javadoc, dependsOn: compileJava) {
    source = sourceSets.main.allJava
    classpath = sourceSets.main.compileClasspath
    destinationDir = javadocJsonDir
    options.docletpath = configurations.jsondoclet.files.asType(List)
    options.doclet = 'capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet'
    options.memberLevel = JavadocMemberLevel.PACKAGE
}

Part of Gradle output

Task :jsonDoclet FAILED javadoc: warning - The old Doclet and Taglet APIs in the packages com.sun.javadoc, com.sun.tools.doclets and their implementations are planned to be removed in a future JDK release. These components have been superseded by the new APIs in jdk.javadoc.doclet. Users are strongly recommended to migrate to the new APIs. javadoc: error - invalid flag: -d Usage: javadoc [options] [packagenames] [sourcefiles] [@files] -overview Read overview documentation from HTML file -public Show only public classes and members -protected Show protected/public classes and members (default) -package Show package/protected/public classes and members -private Show all classes and members -help Display command line options and exit -doclet Generate output via alternate doclet -docletpath Specify where to find doclet class files --module-source-path Specify where to find input source files for multiple modules --upgrade-module-path Override location of upgradeable modules --module-path , -p Specify where to find application modules --add-modules (,) Root modules to resolve in addition to the initial modules, or all modules on the module path if is ALL-MODULE-PATH. --limit-modules (,) Limit the universe of observable modules --source-path Specify where to find source files -sourcepath Specify where to find source files --class-path Specify where to find user class files -classpath Specify where to find user class files -cp Specify where to find user class files -exclude Specify a list of packages to exclude -subpackages Specify subpackages to recursively load -breakiterator Compute first sentence with BreakIterator -bootclasspath Override location of platform class files used for non-modular releases --system Override location of system modules used for modular releases. -source Provide source compatibility with specified release --release Provide source compatibility with specified release -extdirs Override location of installed extensions -verbose Output messages about what Javadoc is doing -locale Locale to be used, e.g. en_US or en_US_WIN -encoding Source file encoding name -quiet Do not display status messages -J Pass directly to the runtime system -X Print a synopsis of nonstandard options and exit

GNU-style options may use = instead whitespace to separate the name of an option from its value.

1 error

FAILURE: Build failed with an exception.

Javadoc Usage

Usage: javadoc [options] [packagenames] [sourcefiles] [@files] where options include: --add-modules (,) Root modules to resolve in addition to the initial modules, or all modules on the module path if is ALL-MODULE-PATH. -bootclasspath Override location of platform class files used for non-modular releases -breakiterator Compute first sentence with BreakIterator --class-path , -classpath , -cp Specify where to find user class files -doclet Generate output via alternate doclet -docletpath Specify where to find doclet class files -encoding Source file encoding name -exclude Specify a list of packages to exclude --expand-requires Instructs the tool to expand the set of modules to be documented. By default, only the modules given explicitly on the command line will be documented. A value of "transitive" will additionally include all "requires transitive" dependencies of those modules. A value of "all" will include all dependencies of those modules. -extdirs Override location of installed extensions --help, -help Display command line options and exit --help-extra, -X Print a synopsis of nonstandard options and exit -J Pass directly to the runtime system --limit-modules (,) Limit the universe of observable modules -locale Locale to be used, e.g. en_US or en_US_WIN --module (,)* Document the specified module(s) --module-path , -p Specify where to find application modules --module-source-path Specify where to find input source files for multiple modules -package Show package/protected/public types and members. For named modules, show all packages and all module details. -private Show all types and members. For named modules, show all packages and all module details. -protected Show protected/public types and members (default). For named modules, show exported packages and the module's API. -public Show only public types and members. For named modules, show exported packages and the module's API. -quiet Do not display status messages --release Provide source compatibility with specified release --show-members Specifies which members (fields, methods, etc.) will be documented, where value can be one of "public", "protected", "package" or "private". The default is "protected", which will show public and protected members, "public" will show only public members, "package" will show public, protected and package members and "private" will show all members. --show-module-contents Specifies the documentation granularity of module declarations. Possible values are "api" or "all". --show-packages Specifies which modules packages will be documented. Possible values are "exported" or "all" packages. --show-types Specifies which types (classes, interfaces, etc.) will be documented, where value can be one of "public", "protected", "package" or "private". The default is "protected", which will show public and protected types, "public" will show only public types, "package" will show public, protected and package types and "private" will show all types. -source Provide source compatibility with specified release --source-path , -sourcepath Specify where to find source files -subpackages Specify subpackages to recursively load --system Override location of system modules used for modular releases --upgrade-module-path Override location of upgradeable modules -verbose Output messages about what Javadoc is doing --version Print version information

Provided by the Standard doclet: --add-stylesheet Additional stylesheet file for the generated documentation --allow-script-in-comments Allow JavaScript in options and comments -author Include @author paragraphs -bottom Include bottom text for each page -charset Charset for cross-platform viewing of generated documentation -d Destination directory for output files -docencoding Specify the character encoding for the output -docfilessubdirs Recursively copy doc-file subdirectories -doctitle Include title for the overview page -excludedocfilessubdir :.. Exclude any doc-files subdirectories with given name -footer Include footer text for each page --frames Enable the use of frames in the generated output (default) -group :... Group specified elements together in overview page -header Include header text for each page -helpfile Include file that help link links to -html4 Generate HTML 4.01 output -html5 Generate HTML 5 output --javafx, -javafx Enable javafx functionality -keywords Include HTML meta tags with package, class and member info -link Create links to javadoc output at -linkoffline Link to docs at using package list at -linksource Generate source in HTML --main-stylesheet , -stylesheetfile File to change style of the generated documentation -nocomment Suppress description and tags, generate only declarations -nodeprecated Do not include @deprecated information -nodeprecatedlist Do not generate deprecated list --no-frames Disable the use of frames in the generated output -nohelp Do not generate help link -noindex Do not generate index -nonavbar Do not generate navigation bar -noqualifier ::.. Exclude the list of qualifiers from the output -nosince Do not include @since information -notimestamp Do not include hidden time stamp -notree Do not generate class hierarchy --override-methods (detail|summary) Document overridden methods in the detail or summary sections -overview Read overview documentation from HTML file -serialwarn Generate warning about @serial tag -sourcetab Specify the number of spaces each tab takes up in the source -splitindex Split index into one file per letter -tag ::

Specify single argument custom tags -taglet The fully qualified name of Taglet to register -tagletpath The path to Taglets -top Include top text for each page -use Create class and package usage pages -version Include @version paragraphs -windowtitle Browser window title for the documentation

GNU-style options may use = instead of whitespace to separate the name of an option from its value.

[Josef-Reichardt]

Is there already someone working on this?

[jmisur]

Would you be interested in proposing a fix via PR?

[Josef-Reichardt]

I will try to supply a PR this week. But I can't do the dokka part because I'm sadly not familiar with kotlin yet.

[fbenz]

Oracle introduced a new Doclet API with Java 9. Our doclet still depends on the old API of Java 8 and below and thus does not work with Java 9+. The solution is to create a new separate doclet for Java 9+. So one needs to maintain two doclets to support both Java 8 and Java 9+. I read a bit in the documentation and looked around for examples, but I did not invest time as we don't need it ourselves yet. So a PR is definitely welcome.

One example of a doclet that offers both versions is https://github.com/talsma-ict/umldoclet (version 2.x is for Java 9+ and version 1.x is for Java 8).

So far Kotlin can only generate Java 6 and Java 8 compatible bytecode and Kotlin's documentation engine Dokka only relation to Java's Doclet is that they can both read Javadoc. Therefore, this issue is not related to Kotlin.

[marceloverdijk]

+1 for Java9+ support.

[rubenpirotteQNH]

We would like to help making it java 9+ compatibele, but we need a clearer view of how you would like to see it solved.

• Do we create a new branch where we implement umldoclet version 2.x , making it java 9+ compatible?
• I do not understand the issue you describe here: https://github.com/ScaCap/spring-auto-restdocs/pull/251#issuecomment-418352493

our current Travis CI setup only uses the same JDK for all projects in this repository.

[jmisur]

Hi @rubenpirotteQNH, we'll determine the next steps shortly and let you know.

[juleshouben]

I added a pull request to make the doclet work with the -d argument provided by gradle. See #259 for more information.