JEP draft: Guidelines for documenting system properties

OwnerJonathan Gibbons
Created2018/11/29 22:38
Updated2018/12/03 04:40


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


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.