JDK 20 brought several changes to JavaDoc. Let’s take a look at how these changes can help you learn about preview features and make linking easier.

Generated IDs for User-Defined Anchors

JavaDoc will now automatically generate an id for user-defined anchors in JavaDoc (i.e., <hN> tags). This will improve the experience of providing links within JavaDoc and for external documentation linking to JavaDocs. Let’s look at how the generated ids work with the below code sample:

/***
 * Some class level JavaDoc
 * 
 * <h2>About Sample Application</h2>
 * 
 * SampleApplication is a sample application for demonstrating Java doc features.
 * 
 * 
 * <h3>Generated ids</h3>
 * 
 * JavaDoc recently introduced generated ids for user-defined anchors.
 * 
 * Some important info here. 
 * @author bkorando
 *
 */

The <h2> and <h3> tags would both get ids generated for them following the pattern of lowercasing of the Latin character contents of the header tag and converting spaces and non-Latin characters to hyphens - and -heading appended as a suffix. So the ids for the above two headers would be; about-sample-application-heading and generated-ids-heading. If there is an id conflict, JavaDoc with append an int accumulator to the end of the id, i.e., generated-ids-heading-1, generated-ids-heading-2.

Simplified Linking to User-Defined Anchors

The @see and {@link} tags have been updated to simplify linking to user-defined anchors. We can explore this update using the links from the previous example in the code snippet below:

/***
 * Learn  about sample application 
 * {@link com.oracle.sip.SampleApplication##about-sample-application-heading here}
 *
 * 
 * @see com.oracle.sip.SampleApplication##generated-ids-heading generated ids
 * @param args some args
 */

Linking to a user-defined anchor can now be down with the fully qualified class or file location, followed by the double pound sign (##) and the name of the anchor; an additional label must be provided as well. The above demonstrates linking the user-defined inks from the first example; {@link com.oracle.sip.SampleApplication##about-sample-application-heading here} and @see com.oracle.sip.SampleApplication##generated-ids-heading generated ids.

Updates to Preview Features in JavaDoc

The Preview page on the official JavaDocs has been updated to make it easier to view the JEPs for preview features and see API changes associated with a preview feature.

A checklist of all preview features included in the JDK release is provided. The title of the JEP is a hyperlink to the relevant JEP, allowing users to learn more about the feature easily. Unchecking the box next to the JEP name will also remove any API changes associated only with that JEP on the page. This can make it easier for users to understand the related API changes to the JDK for a feature which are often difficult to find. Below shows only having a single JEP selected:

Additional Reading

Generalize see and link tags for user-defined anchors (JBS Issue)

Auto-generate ids for user-defined headings (JBS Issue)

List all preview features on the JavaDoc PREVIEW page (JBS Issue)

JavaDoc Preview Page

Happy coding!