Summary

Change the standard doclet so that by default, it does not generate support for frames.

Problem

In times past, to allow for navigation within API documentation, the standard doclet presented indexes in frames on the left side of the window to allow classes, packages and (more recently) modules to be selected for display in the main body of the window.

More recently, the doclet now supports a "search" feature, which provides a more versatile way of finding items to view. Separately, the doclet is moving towards using HTML 5 (only), and the basic support for frames in HTML 5 is less than it was in HTML 4.

The long term goal is to abolish the use of frames for navigation with API documentation, in favor of better alternative mechanisms. In JDK 9, some changes were made in that direction:

• Two new options were added: --frames and --no-frames, to control whether or not support for frames was included in the generated documentation. If neither was specified, the default behavior was to generate support for frames.

• Even when support for frames was included in the generated documentation, frames were not displayed by default; the reader could enable or disable them by clicking on links, labelled FRAMES and NO FRAMES.

• The JDK API documentation allowed the generation of frames, allowing the reader to enable them, using the FRAMES link.

The next step towards eliminating the use of frames is to make the default behavior be equivalent to specifying the --no-frames option.

Solution

Change the default behavior of the doclet so that support for frames is not included in the generated API docs.

The JDK API documentation will use the default behavior, which means it will no longer be possible for the reader to enable the use of frames when viewing the standard JDK API documentation.

Specification

The relevant lines from javadoc -help are these:

--frames      Enable the use of frames in the generated output (default)
--no-frames   Disable the use of frames in the generated output

The word "(default)" will be moved to the second line, as follows:

--frames      Enable the use of frames in the generated output
--no-frames   Disable the use of frames in the generated output (default)

In addition, when the --frames option is specified explicitly, a warning will be produced indicating that support for frames will be removed in a future release.