<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>This is an FYI to announce some initial, long-overdue support in
javadoc for documenting system properties (JDK-5076751).</p>
<p>Currently, system properties are just documented using ad-hoc
narrative text, which is fine if you know where to look for any
given property.</p>
<p>JDK 12 introduces a new inline javadoc tag, <tt>{@systemProperty
<i>property-name</i>}</tt> 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.</p>
<p>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.</p>
<p>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.<br>
</p>
<p>Going forward, in future releases, we expect to explore some
enhancements to this feature. Here are some of the ideas that have
been suggested:</p>
<ul>
<li>Create a "summary page" that lists all the system properties.
This would be somewhat similar to the current top-level
"Constant Values" page.</li>
<li>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.</li>
<li>Update @see and {@link} to be able to refer to system
properties.</li>
<li>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.</li>
</ul>
<p>-- Jon</p>
<p><br>
</p>
<p>[1]:
<a class="moz-txt-link-freetext" href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/System.html#getProperties()">https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/System.html#getProperties()</a><br>
[2]:
<a class="moz-txt-link-freetext" href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/doc-files/net-properties.html">https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/doc-files/net-properties.html</a><br>
[3]:
<a class="moz-txt-link-freetext" href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/Path.html#toAbsolutePath()">https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/Path.html#toAbsolutePath()</a><br>
</p>
<p><br>
</p>
</body>
</html>