JEP draft: Guidelines for documenting system properties

Summary

This informational JEP lays out guidelines for documenting system properties in API documentation.

Motivation

The documentation of system properties in the Java SE and JDK API documentation varies wildly, from tables, such as in the documentation for the System.getProperties() method, to mere references, such as for java.util.secureRandomSeed in ThreadLocalRandom and SplittableRandom.

The new documentation comment tag, {@systemProperty property-name}, introduced in JDK 12, makes it easier to search for system properties, but does not address what it means to properly document a system property, even though many system properties are regarded as a recognized system interface, and tracked by the Compatibility and Specification Review (CSR) process. The defining characteristics of any given system property are beyond the scope of a documentation comment tag, and are best described in the specification for the related API. But, even though there may not be a formal way to specify a system property, there are various characteristics that are worth considering when writing the specification for a property.

This JEP is intended to be a reference when defining new system properties or when updating the specification of existing properties.

Characteristics

• Naming: System properties are normally named with dotted identifiers. A group of related system properties will normally share a common prefix. Identifiers beginning java. are for use within JCP-controlled specifications. Identifiers beginning jdk. are for use within JDK specifications.

• Values: The type and/or set of legal values should always be specified. For example, boolean, string, int, filesystem path, URL, date, and so on. For a boolean type, specify the set of values that correspond to true and false.

  • Restrictions on values: Specify any restrictions on the set of legal values. For example, is there a limited range of valid integer values; does a file path identify a directory, or an existing file?

  • Empty values: Are empty or unset values allowed, and if so, how is that handled?

  • Invalid values: If an invalid value is provided, how is that handled? Is it ignored, or is an error reported?

  • How is the value for a property assigned? Is the value set by the system, or is it typically set by the user, with either the command-line -Dname=value option or by using System.setProperty.

  • Mutability: Is the value mutable? If it is not mutable, what happens if an attempt is made to modify the value? Are such attempts ignored, or is an error reported?

  • Timing: When is the value read? Is the value cached, and if so, when? For example, is it cached before an application's main entry point is called? If the value is cached, what happens if there is a subsequent attempt to modify the value?

• Platforms: If a system property is only defined for use on certain platforms, specify the applicable platforms.

• Scope: What is the scope of the property? Is it part of a Java SE specification, a JDK specification, or some other library. Note that sometimes the provision of a system property is part of the implementation of some specification, and should not be considered part of the specification itself. In such cases, the definition of the property should be clearly and appropriately marked.

• Where: Consider placing the specification of the system property in the smallest unit of public documentation encompassing the APIs either providing or using the property. For example, if a system property will only ever be used by a specific method, consider placing the specification in the specification for the method. If the property will be used by all or many types in a module or package, consider placing the specification in the specification for the module or package. Sometimes, a method, type or package providing a system property may not itself be part of the public API specification. In such situations, place the specification in the smallest enclosing element that is part of the public specification.

• Deprecation: If the system property has been deprecated, give details about alternatives and whether and when support for the system property will be removed.

• Definition, references: Take care to distinguish between the specification of a system property from any possible references to that specification. Each system property should only be defined in a single place, but there may be many references to that specification throughout any related API.