JDK-5076751 : System properties documentation needed in javadocs
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.2
  • Priority: P3
  • Status: Closed
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2004-07-21
  • Updated: 2019-01-08
  • Resolved: 2018-11-12
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 12
12 b20Fixed
Related Reports
CSR :  
JDK-8211132 - Support {@systemProperty } tag
Relates :  
JDK-8213921 - Use {@systemProperty} tag for properties listed in "Networking Properties"
Relates :  
JDK-8213920 - Use {@systemProperty} tag for properties listed in System.getProperties
Description

Name: rmT116609			Date: 07/21/2004


A DESCRIPTION OF THE REQUEST :
The documentation about System Properties for core packages (or extended packages too) is scattered in several files inside J2SE documentation, BUT out of  Javadoc files tree. Some properties are not documented at all.

Does exists any suggestion / JSR (perhaps metadata) about this feature ?


JUSTIFICATION :
I think it woud be very useful to everyone to locate such information in every package overview file (or like constants in constant-values.htm / @value tag)

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Better system customization.
ACTUAL -
Non-centralized documentation.
(Incident Review ID: 235003) 
======================================================================
Comments
This involves the following: * update Doc Comment Spec (will require CSR) * update DocTree API to support new tag (will require CSR) ... not a huge deal, but needs minor updates throughout the package (enum, visitor etc) as well as the new class; need to update DocCommentParser (in javac); need to update doctree tests, in test/langtools/tools/javac/doctree * update doclint Checker ... may need to check valid contents of the tag, if not done in DocCommentParser; may need to update doclint tests, in test/langtools/tools/doclint; * update TagletWriter (internal API) ... just add new method to interface * update TagletWriterImpl ... this is where the main work happens; we will need to refactor the code for @index so that a common core can be shared by @index and @system property; need to handle localization of the string "system property"; need new doclet tests * update the Java SE/JDK doc comments themselves ... identify the system properties that should be documented and use the new tag to wrap the defining instances of those names.
08-09-2018
Revised proposal: Add a new system-defined inline taglet, {@systemproperty <property-name>} that is initially equivalent to {@index <property-name> "system property"} This should have the following effects: 1. The tag is replaced by the property-name, wrapped in an anchor (<a>) tag. 2. The property is automatically indexed (in both A-Z and searchable index) (optional) 3. The property is documented on a new page for all system properties
31-08-2018
Another suggestion ... provide a worker object in the standard doclet that creates a top-level page containing a table that can be populated by custom tags. In the new doclet API, a tablet can access the enclosing doclet and could thereby gain access to shared data like a top level summary page. The top level summary page could be linked from the A-Z index page, along with All Classes, All Packages, etc
09-03-2018
Modifying the previous comment... 1. The property is listed in the block tags for the element that defines the property We could generate a <table> for all the @systemProperty tags defined on an element so that the properties are tabulated "nicely" together.
09-03-2018
Consider new block tag @systemProperty <property-name> <description> This could have the following effects: 1. The property is listed in the block tags for the element that defines the property 2. The property is automatically indexed (in both A-Z and searchable index) 3. The property is documented on a new page for all system properties
13-02-2018
It's not clear this is worthwhile. For now, I think we need to revisit whether there is enough interest to use such a feature. Modeling it on constant fields, and the summary page for constant field values would be reasonable and not too difficult. A somewhat unrelated thought would be to use the {@index} mechanism to make the names of system properties searchable, but that would be the work of the component owners; it's not a javadoc issue per se. Closing as Wont Fix for now; we can revisit as needed.
12-02-2018
EVALUATION Accepted. ###@###.### 2004-07-22
22-07-2004