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.

This week we’re looking at less exciting JEPs. However they are important for ease of documentation and documentation accessibility. We’ll look at JEP 224: HTML5 Javadoc and JEP 225: Javadoc Search.

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:

javadoc -J-version

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:
AccountTypeCalculator

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.

IntelliJ IDEA options

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.

You can specify the output for the documentation files. Here I’ve lazily added an extra folder: JavaDoc configThen you can view the results:

Javadoc result

Going into the AccountTypeCalculator, we can see the method details generated from the comments:

Method details

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.

Javadoc Search

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 search.js Javascript file, along with indexes generated when the javadoc is generated. A search box is available on the generated API pages:

search results

This will be added by default, but can be turned off with the argument: -noindex.

What can be searched?

The following will be indexed and searchable:

  • Declared names of modules
  • Packages
  • 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.

 

Next up: Concurrency Updates

Java 9 series: HTML5 and Javadoc

About The Author
- Katharine is a Java developer by trade, turned Community & Content Manager for Voxxed. Helping developers learn and share knowledge. Contact me at kbe@voxxed.com with any news, articles or tutorials.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>