FYI: new javadoc tag to document system properties
Joseph D. Darcy
joe.darcy at oracle.com
Wed Nov 14 22:34:22 UTC 2018
Hello,
For future CSR requests involving system properties, please document the
properties using these javadoc facilities.
Thanks,
-Joe
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()
>
>
More information about the security-dev
mailing list