This is the forth in a series of articles looking at some of the JDK Enhancement Proposals (JEPS) hoping to make their way into Java 9. Last week we looked at changes to the JVM.
Javadoc in HTML5
Javadoc is a tool for generating API documentation. It generates the documentation in HTML format. JEP 224 enhances the
javadoc tool to generate HTML5 markup. It currently generates pages in HTML 4.01.
The easiest way to learn about
javadoc and experience the benefits to your documentation is to use it. Download the Java 9 Early Access Release. You can check the Javadoc version is “9” by running:
Check you get:
java version "9-ea" Java(TM) SE Runtime Environment (build 9-ea+138) Java HotSpot(TM) 64-Bit Server VM (build 9-ea+138, mixed mode)
Looking at the example code from Just enough code: Mutation Testing, we can add comments to the class to convey more information about what the code is doing:
This project is using the Java 9 Early Access Release as its SDK. If you are using an IDE such as IntelliJ IDEA, you can use the “Tools” / “Generate Javadoc …” option to create the Javadoc.
In order to generate a HTML5 Javadoc, the parameter
-html5 needs to go in the command line arguments.
To generate the document on the command line, you would run:
javadoc [options] [packagenames] [sourcefiles] [@files]
For information on how to do this, see earlier Javadoc documentation.
Going into the AccountTypeCalculator, we can see the method details generated from the comments:
HTML5 and Accessibility
Using HTML5 confers the benefits of the easier HTML5 structure. It also implements the WAI-ARIA standard for accessibility. This aims to make it easier for people with physical or visual impairments to access
javadocs pages using tools such as screen readers. Sites such as HTML5Accessibility track which HTML5 features are accessibly supported by major browsers: meaning, available for use by people who rely on assistive technologies.
JEP 225 gives the ability to search a
javadoc for program elements and tagged words and phrases. This has been added as “the Javadoc-generated API documentation pages are hard to navigate if you’re not already familiar with their layout”.
This is implemented client side, with a new
javadoc is generated. A search box is available on the generated API pages:
This will be added by default, but can be turned off with the argument:
What can be searched?
The following will be indexed and searchable:
- Declared names of modules
- Types and members
- The simple name of method parameter types
Method parameter names won’t be indexed. Search terms or phrases can be added with an
@index inline tag.
For more information on using the
javadoc tool, see the Oracle guide here.