FYI: new javadoc tag to document system properties

[Joseph D. Darcy]

Hello,

For future CSR requests involving system properties, please document the 
properties using these javadoc facilities.

Thanks,

-Joe

On 11/14/2018 2:27 PM, Jonathan Gibbons wrote:
> This is an FYI to announce some initial, long-overdue support in 
> javadoc for documenting system properties (JDK-5076751).
>
> Currently, system properties are just documented using ad-hoc 
> narrative text, which is fine if you know where to look for any given 
> property.
>
> JDK 12 introduces a new inline javadoc tag, {@systemProperty 
> /property-name/} which can be used to "declare" the name of a system 
> property. You can use this tag as a drop-in replacement for the 
> plain-text property name; it will have no overt effect on the 
> narrative text, but it will cause the property name to be put into the 
> search index and the A-Z index. Thus, property names will become 
> searchable, to allow users to easily find the definition of any such 
> system property.
>
> Adding support into javadoc is only part of the story. Now that the 
> support is in javadoc, we want to update the API documentation, so 
> that the documentation is updated for all Java SE and JDK system 
> properties.
>
> Where should the tag be used?  The tag should be used in the text of 
> the defining instance of the property.  This is where the 
> characteristics of the system property are described, which may 
> include information like: "what is the property for", "how and when is 
> it set", "can it be modified", and so on. For example, it could be 
> used in the docs for System.getProperties [1] or Networking Properties 
> [2] In general, it should -not- be used in situations that merely 
> refer to the system property by name.  For example, the docs for 
> Path.toAbsolutePath [3] make a reference to the system property 
> user.dir, but that is not a definition of the property.
>
> Going forward, in future releases, we expect to explore some 
> enhancements to this feature. Here are some of the ideas that have 
> been suggested:
>
>  * Create a "summary page" that lists all the system properties. This
>    would be somewhat similar to the current top-level "Constant Values"
>    page.
>  * Add information regarding the "scope" of the definition: is it
>    defined by the Java SE specification, or JDK, or JavaFX, etc. This
>    information could be used to organize the content on the summary page.
>  * Update @see and {@link} to be able to refer to system properties.
>  * Allow a short description to be included in the {@systemProperty}
>    tag. This text could be included in the search index, the A-Z index,
>    and the summary page.
>
> -- Jon
>
>
> [1]: 
> https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/System.html#getProperties()
> [2]: 
> https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/doc-files/net-properties.html
> [3]: 
> https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/Path.html#toAbsolutePath()
>
>