FYI: new javadoc tag to document system properties

[Roger Riggs]

Hi,

If a system property is defined and specified as supported then it needs 
a public declaration and specification as part of the public class or 
package documentation.
Checking for and adding the tag will be a good way to reconfirm property 
definitions are in the right place.

Would it be reasonable to use only core-libs-dev for any remaining 
discussion?
Seeing it on 5 aliases doesn't seem productive.

$.02, Roger


On 11/15/2018 11:17 AM, Xuelei Fan wrote:
> 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() 
>>
>>
>>