Summary

Update the javadoc tool to support the use of "preview" features.

Problem

JEP 12 [1] describes JDK support for "preview" language and VM features. To enable the use of such features in source code, the user must specify both a source version (using either the -source or --release option) and must specify a new option --enable-preview. Support for this is being added to javac [2] and needs to be added to the javadoc tool as well.

Solution

Add a new option --enable-preview for the javadoc tool. The option will be delegated to javac, in the same way as for other javadoc options that are handled internally by javac. No other action is required. The check that either -source or --release is also specified will be done by javac, and can be assumed by the javadoc tool.

Specification

A new option, --enable-preview, that takes no arguments.

When present, an option to specify the current source version must also be present.

When specified, the javadoc tool will accept the use in of preview features defined in the given source version for any source and class files it reads. If not specified, the use of preview features in any files read by the tool will cause appropriate error messages to be generated.

The exact details of the behavior are specified in the corresponding CSR for javac [3].

The presence, or absence, of the option does not affect the overall set of generated pages. Some specific individual preview features may require some changes to the output, but that will be addressed when designing those features.

[1] http://openjdk.java.net/jeps/12
[2] https://bugs.openjdk.java.net/browse/JDK-8199194
[3] https://bugs.openjdk.java.net/browse/JDK-8200312