FYI: new javadoc tag to document system properties

Bill Shannon bill.shannon at
Thu Nov 15 06:58:09 UTC 2018

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:
>> 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.,
>> 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]:
>>> [2]:
>>> [3]:

More information about the jdk-dev mailing list