FYI: new javadoc tag to document system properties

[Jonathan Gibbons]

Roger,

In general, and without looking at the JCE API, I note that 
module-info.java is where providers are declared (i.e. the provides 
directive and @provides tag.) So this might indeed be a reasonable place 
to document information relevant to the provider, such as any properties 
it might support.

A different way to phrase your comment would be to suggest putting the 
info about system properties in the smallest enclosing publicly 
documented element (module, package, type, etc). Sometimes, especially 
with provider modules, the module-info.java is the only place to put the 
information.

-- Jon


On 11/16/2018 06:49 AM, Roger Riggs wrote:
> Hi,
>
> module-info.java isn't a good place; its too far from the relevant API 
> that it affects.
> The property should be documented where it make sense and where 
> developers
> will find it.
>
> In this case, since it is provider specific,  it makes sense to define 
> the property
> where the provider is described or documented.  If the provider is not 
> defined anywhere,
> then its all implementation and probably should *not* be documented.
>
> Roger
>
> On 11/15/2018 10:42 PM, Weijun Wang wrote:
>> I had also thought about this. In JCE, the API and implementation 
>> (aka provider) might even be in different modules, if some system 
>> properties only apply a specific provider, we can put them into 
>> module-info.java of that module.
>>
>> We do support the new tag in module-info.java, right?
>>
>> Thanks
>> Max
>>
>>> On Nov 16, 2018, at 12:31 AM, Roger Riggs <Roger.Riggs at oracle.com> 
>>> wrote:
>>>
>>> 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()
>>>>>
>>>>>
>