Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8202961

Javadoc should not generate frames by default

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 11
    • Component/s: tools
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      No functionality is being added or removed at this time; the change just affects the default behavior of the tool when no relevant option is specified.
    • Interface Kind:
      add/remove/modify command line option

      Description

      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.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                jjg Jonathan Gibbons
                Reporter:
                bpatel Bhavesh Patel (Inactive)
                Reviewed By:
                Maurizio Cimadamore
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: