FYI: new javadoc tag to document system properties

[Jonathan Gibbons]

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()