Loading... (original) (raw)

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