FYI: new javadoc tag to document system properties

[Jonathan Gibbons]

Bill,

The intent is that this feature is just for system properties. In 
upcoming releases, we expect to extend the feature to provide a 
top-level summary page listing all the system properties.

For other kinds of properties, such as the JavaMail session properties, 
you can use

     {@index property-name short-description}

such as
     {@index mail.smtp.user JavaMail session property}

-- Jon


On 11/14/2018 10:58 PM, Bill Shannon wrote:
> Could we just call them "Properties" ib the index, to allow this new 
> feature to be more widely used?
>
> Priya Lakshmi Muthuswamy wrote on 11/14/18 9:43 PM:
>>
>> When a property-name is wrapped with {@systemProperty propertyname} 
>> tag, the search Index and A-Z index will have
>> short description mentioning it as system property.
>>
>> In the defining page, the property name will be wrapped within a html 
>> anchor and index entry will point to this.
>> /java.base/java/lang/System.html#java.version.
>>
>> Thanks,
>> Priya
>> On 11/15/2018 9:45 AM, Bill Shannon wrote:
>>> JavaMail defines a bunch of System properties as well as JavaMail Session
>>> properties.  For example:
>>> https://javaee.github.io/javamail/docs/api/javax/mail/internet/package-summary.html#package.description
>>>
>>> Would this tag be usable for both?
>>>
>>> Would there be any reason to distinguish between System properties and
>>> Session properties when using this tag?  If it's just adding an entry to
>>> the index that links back to the defining page, that distinction doesn't
>>> seem necessary.
>>>
>>> The defining entries in the page above use html anchors, e.g.,
>>> https://javaee.github.io/javamail/docs/api/javax/mail/internet/package-summary.html#mail.mime.charset
>>> Is there a way to cause the tag to generate an index entry that uses
>>> the anchor, or does it just link to the defining page?
>>>
>>>
>>> Jonathan Gibbons wrote on 11/14/18 2:27 PM:
>>>> 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()
>>>>
>>>>
>>>>
>