FYI: new javadoc tag to document system properties

[Priya Lakshmi Muthuswamy]

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