FYI: new javadoc tag to document system properties

[Xuelei Fan]

In JCE and JSSE, the public APIs definition (javax.net.ssl) and the 
internal implementation (sun.security.ssl) are separated.  The system 
property can be defined in the internal implementation classes.  I think 
we should add the @systemProperty on the public APIs, right?

The public API class and the implementation class may be not a 
one-to-one map.  Multiple public APIs may be impacted by the system 
property.  How to handle such cases?

Thanks,
Xuelei

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