|
CSR :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
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
|