FYI: new javadoc tag to document system properties
Roger Riggs
Roger.Riggs at oracle.com
Thu Nov 15 16:31:04 UTC 2018
Hi,
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.
Checking for and adding the tag will be a good way to reconfirm property
definitions are in the right place.
Would it be reasonable to use only core-libs-dev for any remaining
discussion?
Seeing it on 5 aliases doesn't seem productive.
$.02, Roger
On 11/15/2018 11:17 AM, Xuelei Fan wrote:
> 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?
>
> 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?
>
> Thanks,
> Xuelei
>
> On 11/14/2018 2:27 PM, Jonathan Gibbons wrote:
>> 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()
>>
>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/security-dev/attachments/20181115/4657529e/attachment.htm>
More information about the security-dev
mailing list