Bug ID: JDK-8215040 Allow more info in the {@systemProperty} tag

Type: Enhancement
Component: tools
Sub-Component: javadoc(tool)

Priority: P3
Status: New
Resolution: Unresolved

Submitted: 2018-12-08
Updated: 2023-08-30

It is suggested that we should allow the user to specify more info in the {@systemProperty} tag.

This info might include:

* a short description to include in the search index and property summary page
* the "scope" of the name (Java SE, JDK, etc)
* whether the name is deprecated or not

There are no proposals for syntax at this stage.  [See proposed syntax in comments]

Each change to the tag implies corresponding changes to elsewhere in the doclet, to utilize that information. For example, scope and/or description would be reflected on the property summary page; deprecation info would appear on the deprecation page.

Yes, JDK-8201533 teaches DocCommentParser to parse snippet tag attributes. However, this new parsing skill is somewhat specific to the snippet tag. This is because colon (`:`) separates attributes, if any, from the body of the snippet tag. I assume that we envision NO body in @systemProperty tag. If so, then the parsing method used for @snippet will have to be adapted for @systemProperty.
30-08-2021
The changes to DocCommentParser have now been done, as part of JDK-8201533
29-08-2021
This will require changing `com.sun.tools.javac.parser.DocCommentParser` to support tag attributes. That might be done in the context of JDK-8201533.
03-09-2020
proposed syntax is {@systemProperty [scope=<label>] <property-name> <short-description>} Guidelines ... descriptions in tags so far always come last. Options in tags will be new, and after offline email discussion, the proposed format is <name>=<value> appearing after the tag name. The '=' will typically be used to indicate the presence of an option, as different from the info that follows.
17-10-2019
[~prappo] The proposed tag attributes would be "opt-in and supplied by authors. The proposed "description" is intended to be a short phrase summarizing the property, perhaps explaining the name in cases where the name is not self-explanatory. The description should not be a full formal definition of the property. As a guideline, I suggest that the property tag should be less than 64-80 characters long. The tags should not be significantly worse/longer than "index" tags. Also, the "systemProperty" tag has been branched off from the "index" tag in order to facilitate a summary page of all documented system properties, since system properties are effectively a somewhat-public interface. For example, note, the documented system properties are covered by the CSR process.
17-10-2019
I understand that the ability to specify additional info along with the property name is why the "systemProperty" tag has been branched off from the "index" tag in the first place (see JDK-8211132). > It is suggested that we should allow the user to specify more info in the {@systemProperty} tag. I would like to have a look at those suggestions. Given the differences between contexts where properties are defined in the JDK, I cannot immediately see any meaningful way of extracting tag attributes. One of my concerns is that we might end up with the most bulky and mouthful tag in the whole javadoc.
17-10-2019