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

javadoc should auto-link to platform classes

    Details

    • Type: Enhancement
    • Status: New
    • Priority: P3
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: tools
    • Labels:
      None

      Description

      It has long been understood that correct use of javac and javadoc `-source` option should be accompanied by an equivalent `-bootclasspath` option ... and equally understood that this is often-times difficult in a development environment, since it requires access to an installed version of the relevant API. This led to the introduction of the `--release` option for both java and javadoc, such that the compilation environment automatically provides access to the appropriate version of the platform classes.

      There is a similar issue in javadoc with respect to linking to the API docs for the platform classes. The issue is not as severe (or as well known) as the `-bootclasspath` problem, because it is often common practice to not link to the platform API docs at all, but for those that do want to link to the platform API docs, it is similarly tedious. Either one must have access to the Internet, to use the `-link` option, or one must have access to a local version of the API description file (originally packages.list, now element.list) for the appropriate API. If one uses the `link` option to access the API description file via the Internet, one must deal with the irregularities in the URLs for the API docs for different releases. See, for example, this code in the Maven javadoc plugin, that has to maintain a mapping table:
      https://github.com/apache/maven-javadoc-plugin/blob/master/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java#L1761

      It would be better if javadoc itself knew the mapping table, and/or provided local copies of the API description files, so that clients did not have to ... whether the clients are running javadoc directly, or via a plugin for a build system like Ant or Maven.

      Note ... it should still be possible for a user to override the default location, in the same way that a user can override the location of the compiled platform classes. Such overriding should presumably be done with the existing `-link` or `-linkoffline` options. This implies that javadoc should be able to examine the overall set of `-link*` options, to determine if any of the options provide a URL for the platform classes, such as by looking for a URL for the `java.lang` package. If no such URL is provided, then javadoc can provide a default.

      It is arguably an open question whether it should be possible to disable this feature, so that platform classes are _not_ linked.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                Unassigned
                Reporter:
                jjg Jonathan Gibbons
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated: