Java 9 series: HTML5 Javadoc
This is the forthin 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 atchanges to the JVM.
This week we’re looking at less exciting JEP, but important for accessibility: JEP 224: html5 Javadoc .HTML5 Javadoc
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.Itcurrently generates pages in HTML 4.01 .
The easiest way to learn about javadoc and experiencethe benefits to your documentation is to use it. Download theJava 9 Early Access Release. You can check the Javadoc version is “9” by running:
javadoc -J-versionjava 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 moreinformation 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 canuse 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 documenton the command line, you would run:javadoc [options] [packagenames] [sourcefiles] [@files]
For information on how to do this, see earlier Javadoc documentation .You can specify the output for the documentation files.Here I’ve lazily added an extra folder:
Then you can view the results:
Going into the AccountTypeCalculator, we can see the method details generated from the comments:
Using HTML5 in Javadocs confers the benefits of the easier HTML5 structure. Italso implements the WAI-ARIA standard for accessibility. This aims to make it easier for people with physical or visual impairments to access 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.
For more information on using the Javadoc tool, see the Oracle guide here .