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

New javadoc options for auto-link to platform classes

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 16
    • Component/s: tools
    • Labels:
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Interface Kind:
      add/remove/modify command line option

      Description

      Summary

      Add options to disable and customize the linking behaviour to platform classes in Javadoc generated documentation.

      Problem

      With the introduction of automatic links to Java platform classes arises the need to control or customize this behaviour. People may want to disable linking to platform classes, or generate links directed at some other location.

      Solution

      Introduce two new options to disable linking to platform classes and to change the target of the generated links.

      Specification

      The following two options will be added:

       --no-platform-links
            Do not generate links to the platform documentation

      The --no-platform-links option causes Javadoc to not generate Java platform links. The output is the same as before the addition of the platform link feature.

      --link-platform-properties <url>
            Link to platform documentation URLs declared in properties file at <url>

      The --link-platform-properties option causes Javadoc to generate Java platform links using the URLs defined in a properties file at <url>. The properties file must contain entries with the following format, where <release> is the numeric feature release and <URL> is the base URL of the API documentation for that release:

      doclet.platform.docs.<release>=<URL>

      For example, a properties file with the content listed below causes Javadoc to generate platform documentation links to https://some.domain/docs/<N>/api/ with <N> being the major feature release of the current Javadoc execution and 7 <= N <= 16.

      doclet.platform.docs.7= https:/example.com/docs/7/api/
      doclet.platform.docs.8= https://example.com/docs/8/api/
      doclet.platform.docs.9= https://example.com/docs/9/api/
      doclet.platform.docs.10=https:/example.com/docs/10/api/
      doclet.platform.docs.11=https://example.com/docs/11/api/
      doclet.platform.docs.12=https://example.com/docs/12/api/
      doclet.platform.docs.13=https://example.com/docs/13/api/
      doclet.platform.docs.14=https://example.com/docs/14/api/
      doclet.platform.docs.15=https://example.com/docs/15/api/
      doclet.platform.docs.16=https://example.com/docs/16/api/

      If the argument passed to the --link-platform-properties option does not specify a URL scheme the argument is interpreted as file path.

      If the properties file passed as argument to the --link-platform-properties option cannot be read javadoc exits with an error. If the properties can be read but does not contain an entry for the current release no error is raised, but no platform links are generated.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              hannesw Hannes Wallnoefer
              Reporter:
              jjg Jonathan Gibbons
              Reviewed By:
              Jonathan Gibbons
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: