JEP draft: Customizable Inline Notes in Java API Documentation

Summary

Add a new note tag for notes in the JavaDoc Standard Doclet, and provide a mechanism for registering custom note tags.

Goals

• Allow API authors to create rich-content notes using a new standard note tag.
• Provide a mechanism to declare custom tags based on the new standard tag.
• Design the new feature as an extension of existing functionality for custom tags.

Non-Goals

• It is not a goal to replace or change the way custom block tags are defined using the -tag option. Rather, the intention is to enhance existing functionality by adding a standard tag, supporting inline tags and improving customizability.

Success Metrics

Provide a mechanism that is adopted by documentation authors in a way that enhances the usefulness of API documentation without negatively affecting its appearance or readability.

Motivation

Effective API documentation sometimes requires authors to highlight supplemental information — such as warnings, tips, or background context — that is distinct from the main explanatory text. The most effective way to communicate these insights is by calling them out with special formatting and labels (such as "Note," "Warning," or "Example"), making them immediately noticeable and easy to understand. We refer to all these pieces of information as notes.

Notes of all kinds — warnings, tips, examples, background, rationale, etc — work best in the main descriptive content, where they can immediately illuminate a complex point. That is, notes are inline by their nature. They are different than other supplementary information that works best when set off from the main description, such as the Parameters: and Returns: blocks.

Currently, JavaDoc does not support a standardized approach for embedding such inline notes within the main descriptive content. The existing JavaDoc -tag option only supports custom tags as block tags, which are rendered after the main description. This limits their usefulness for context-sensitive notes that should appear directly alongside related documentation content.

Attempts to implement inline notes using the jdk.javadoc.doclet.Taglet interface are also unsatisfactory. Inline tags created with this mechanism cannot contain rich text or nested tags, such as {@link} or {@code}, restricting the ability to provide comprehensive, well-formatted guidance where it matters most. Furthermore, the Taglet API does not provide access to the Standard Doclet’s capabilities for rendering rich, nested documentation content, making this approach complex and inconsistent.

Introducing a standard JavaDoc tag for inline notes would directly address these shortcomings. This feature would empower API authors to systematically highlight important information, while ensuring notes are rendered with consistent formatting and rich content. As a result, Java documentation would become more readable, actionable, and predictable for consumers, while also streamlining the documentation process for API designers.

Description

The note Tag

A new note tag is introduced with the following syntax:

@note body
@note [ attributes ] body
{@note body }
{@note [ attributes ] body }

The note tag can be used both as block and inline tag. When used as block tag, the output is grouped with other block tags after the main descriptive text. As an inline tag, the output is rendered at the site of its declaration within the descriptive text.

The attributes use the form of name=value pairs. The attribute name is a simple identifier. The attribute value may be an unquoted, single-quoted or double-quoted string; no escape characters are supported. Attributes are separated from each other by whitespace, such as space or newline characters.

The body of note tags may contain rich text including nested inline JavaDoc tags such as {@link}, {@code}, or {@snippet}, as well as HTML elements. As an inline tag, it is terminated by the first unbalanced closing curly brace character. This means that an inline {@note} tag may only contain balanced pairs of curly-brace characters, a restriction that is common to all inline tags. When used as block tag, it is terminated by the beginning of the next block tag or the end of the comment.

A note tag is rendered as a text block with a header which defaults to the localized string Note:. The output format is similar for both inline and block note tags, although inline tags may use a slightly more distinctive layout to help them stand out against the surrounding text.

Consider the following tag:

{@note This is a note.}

The output generated by JavaDoc resembles the following:

Note: This is a note.

(Note that the exact formatting of the output is beyond the scope of this document.)

Attributes

The note tag recognizes various attributes to customize the content and layout of the generated note.

The header attribute can be used to set the content of the note header. For example, the following tag produces a note with the string Caution: as header.

{@note [header='Caution:'] Beware of the dog!}

The generated output may look as follows:

Caution: Beware of the dog!

The kind attribute is used to describe the kind of content of a note. The value of the kind attribute is encoded as a CSS class in the HTML element representing the note, using note-tag- as prefix.

For example, consider the following tag:

{@note [kind=important] This is important.}

The generated output for the tag contains an HTML element with CSS class note-tag-important.

The default stylesheet contains declarations for various kinds of notes:

• note (default value)
• tip
• important
• warning
• caution
• example

User-defined stylesheets can be used to declare styles for user-defined custom notes.

It is allowed to use other attributes in note tags than the standard ones listed above. Non-standard attributes are included as custom data attributes in the HTML element representing the note and may be used in stylesheets to customize note layout.

The -tag Option and Custom Tags

The existing -tag option is modified to create custom tags that are aliases for the note tag. The value of the kind attribute of such custom tags is set to the tag name and the value of the header attribute is set to the tag header provided in the command line argument. This does not change the behaviour of existing custom tags, but extends their use to inline and attributed notes. Other features of the -tag option, such as the argument to define the allowed locations of the tag, remain unchanged.

For example, consider the following command line arguments:

-tag 'warning:a:Warning:'

This creates a custom warning tag that is an alias to a note tag and can be used both as inline and block tag. An example block tag might look like this:

@warning This is a warning.

The tag above is equivalent to the following note tag:

@note [kind='warning' header='Warning:'] This is a warning.

Both tags above produce the identical output shown below:

Warning: This is a warning.

Custom tags may contain attributes, including the standard kind and header attributes which, when present, override the values in the custom tag.

Guidelines for Using the note Tag

Inline notes disrupt the flow of text and may distract the reader, so they should be used sparingly and judiciously. Not every sentence or paragraph that contains a note, warning or tip needs to be a formatted as a note tag. If a sentence or paragraph is part of the surrounding text, it may not benefit from special formatting.

The following examples show cases where the use of inline notes may be appropriate:

• Notes that provide context, background or other supplemental information that may be of interest to the reader. An example would be the following note in the documentation of method ExecutorService.submit(Callable):

  Note: The Executors class includes a set of methods that can convert some other common closure-like objects, for example, PrivilegedAction to Callable form so they can be submitted.

• Notes that contain warnings or other important messages that deserve to be highlighted so that the reader does not overlook them. An example is the following note in the description of the List interface:

  Note: While it is permissible for lists to contain themselves as elements, extreme caution is advised: the equals and hashCode methods are no longer well defined on such a list.

  Maybe a "Caution" header and style would be more appropriate here than the generic "Note".

Alternatives

Several alternative approaches were considered, including the introduction of a new API to enable the implementation of custom note tags, or a new JavaDoc option to configure note tags via command line.

Extending the jdk.javadoc.doclet API to enable implementation of note tags would either have meant to enhance the existing Taglet API to support rich inline content, or to add a new dedicated API. Both approaches seemed too heavy for the single purpose of implementing inline notes. Also, using an API-based approach would still require custom code to be written, without the simplicity of an out-of-the-box solution.

It was considered to add a new JavaDoc option specifically for inline notes, rather than extending the existing -tag option. However, the new option would have duplicated the exsting one in many aspects, making JavaDoc usage more complicated while offering little benefit over an enhanced -tag option.

An early draft of this document proposed a templating mechanism to customize layout of generated notes. This was also found to add too much complexity, while a CSS-based solution offers plenty of flexibility for common use cases.

Testing

The new feature will be tested using the standard test infrastructure for JavaDoc features, such as jtreg tests and related tools to check the correctness of the generated documentation.

Risks and Assumptions

The rationale for providing two distinct ways to use the new feature — the raw note tag and custom tags configured via command line option — is that these mechanisms will appeal to different sets of users. For smaller and more informal projects, the standard note tag provides a flexible way to create arbitrary notes, without requiring support from the build system. For larger projects, configuration of custom tags via command line option provides a way to provide a sanctioned set of notes with more convenient simple tag syntax.

One risk with the new note tag is that it could be used excessively, and in places that would benefit more from continuous text. This lies of course mainly in the responsibility of API documentation authors. Including advise for good practice of the new tag in its documentation could help to mitigate the problem.