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.ri...@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()
>>>
>>>
>>>
>
