<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFCC">
Hi,<br>
<br>
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. <br>
Checking for and adding the tag will be a good way to reconfirm
property definitions are in the right place.<br>
<br>
Would it be reasonable to use only core-libs-dev for any remaining
discussion?<br>
Seeing it on 5 aliases doesn't seem productive.<br>
<br>
$.02, Roger<br>
<br>
<br>
<div class="moz-cite-prefix">On 11/15/2018 11:17 AM, Xuelei Fan
wrote:<br>
</div>
<blockquote type="cite"
cite="mid:9e6bf54a-3193-fcb9-a523-9411ae83e952@oracle.com">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?
<br>
<br>
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?
<br>
<br>
Thanks,
<br>
Xuelei
<br>
<br>
On 11/14/2018 2:27 PM, Jonathan Gibbons wrote:
<br>
<blockquote type="cite">This is an FYI to announce some initial,
long-overdue support in javadoc for documenting system
properties (JDK-5076751).
<br>
<br>
Currently, system properties are just documented using ad-hoc
narrative text, which is fine if you know where to look for any
given property.
<br>
<br>
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.
<br>
<br>
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.
<br>
<br>
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>
<br>
Going forward, in future releases, we expect to explore some
enhancements to this feature. Here are some of the ideas that
have been suggested:
<br>
<br>
* Create a "summary page" that lists all the system
properties. This
<br>
would be somewhat similar to the current top-level "Constant
Values"
<br>
page.
<br>
* Add information regarding the "scope" of the definition: is
it
<br>
defined by the Java SE specification, or JDK, or JavaFX,
etc. This
<br>
information could be used to organize the content on the
summary page.
<br>
* Update @see and {@link} to be able to refer to system
properties.
<br>
* Allow a short description to be included in the
{@systemProperty}
<br>
tag. This text could be included in the search index, the
A-Z index,
<br>
and the summary page.
<br>
<br>
-- Jon
<br>
<br>
<br>
[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>
<br>
<br>
</blockquote>
</blockquote>
<br>
</body>
</html>