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

Support {@systemProperty <name>} tag

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 12
    • Component/s: tools
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      source
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      A new tag is added for use in documentation comments. There is minimal risk of clashing with any like-named user-defined tag, and no risk of any issue in the main Java SE and JDK documentation.
    • Interface Kind:
      Java API, File or wire format
    • Scope:
      JDK

      Description

      Summary

      Provide a means to document system properties in documentation comments.

      Problem

      There is no explicit support for documenting the system properties "defined" by an API. This leads to inconsistent ad-hoc techniques that are not readily searchable.

      Solution

      Provide a new inline tag {@systemProperty property-name}, which is initially informally equivalent to {@index property-name system property}, where property-name represents the name of a system property. In other words, instances of the tag are replaced inline by the name of the property, and the name is put in both the interactive search index, and the static A-Z index.

      The tag can be used in the documentation comments for modules, packages, types, fields and executable members.

      Future extensions, but not a goal at this time:

      • Create a new "summary" page that enumerates all the system properties defined in all the declarations being documented. This might be modeled on the "Constant Values" page.

      • Extend @see and {@link} to be able to refer to places where a system property is defined with {@systemProperty}.

      Alternatives:

      Instead of supporting a new tag, we could just establish a convention of using the equivalent {@index} tag. However, that would make it harder to extend the feature in future with additional behavior specific to system properties.

      Instead of using an inline tag, we could use a block tag, similar to tags like @param, @return, etc. This would allow the doclet to provide more support for the display of the definitions. However, such a change would be much more disruptive to existing documentation, which already uses tables, lists and other display artifacts to show the properties defined in an API.

      Specification

      There are two specifications to be updated:

      1. The Documentation Comment Tag Specification

        {@systemProperty property-name }

        Identify property-name as the name of a system property. The name should be a "dotted identifier". In particular, it must not contain white space characters, or characters such as }. No other content is permitted in the tag; the possibility of additional content is reserved for future use. The tag can be used in the documentation comments for modules, packages, types, fields and executable members.

        Exact diff of doc-comment-spec attached

      2. The com.sun.source.doctree package in the Compiler Tree API.

        A new subtype of InlineTagTree is introduced, together with a new member in DocTree.Kind, as well as corresponding updates for DocTreeVisitor, etc.

        Specification attached, also available at http://cr.openjdk.java.net/~pmuthuswamy/5076751/specdiff

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                pmuthuswamy Priya Lakshmi Muthuswamy (Inactive)
                Reporter:
                rmandalasunw Ranjith Mandala (Inactive)
                Reviewed By:
                Mandy Chung, Roger Riggs
              • Votes:
                0 Vote for this issue
                Watchers:
                6 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: