RFR: 8296546: Add @spec tags to API [v3]

Jonathan Gibbons jjg at openjdk.org
Thu Dec 1 19:57:33 UTC 2022


On Wed, 23 Nov 2022 23:04:36 GMT, Joe Wang <joehw at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Remove updates from unexported files
>
> src/java.xml/share/classes/javax/xml/XMLConstants.java line 35:
> 
>> 33:  * @spec https://www.w3.org/TR/REC-xml-names Namespaces in XML 1.0 (Third Edition)
>> 34:  * @spec https://www.w3.org/TR/xml-names11 Namespaces in XML 1.1 (Second Edition)
>> 35:  * @spec https://www.w3.org/TR/xmlschema-1 XML Schema Part 1: Structures Second Edition
> 
> Hi Jon,
> 
> I would agree with what Alan said earlier that the @see ref can be dropped. This particular class (XMLConstants.java [1]) is a good example for that argument: in the resulting javadoc, 5 specs were listed in the "External Specifications" section, 6 in "See Also:", and then they were listed again for each field. That's a lot of duplicates. Adding to the confusion was that the @spec and @see were not always the same, e.g. @spec XML 1.0.
> points to the fifth edition while @see second.
> 
> A minor comment is that the '@spec's were rendered in one line while the @see refs a list. I would see the later is easier to read.
> 
> [1] http://cr.openjdk.java.net/~jjg/8296546/api.00/java.xml/javax/xml/XMLConstants.html

The presentation of lists of `@spec` tags was fixed separately (JDK-8297802), and is incorporated into the latest docs that demo this work.   The same algorithm is now used for both `@see` and `@spec` tags ... if the links are short and do not contain commas, they will be displayed as an inline list; otherwise, they will be displayed in a bulleted list.

-------------

PR: https://git.openjdk.org/jdk/pull/11073



More information about the security-dev mailing list