On Wed, 23 Nov 2022 23:04:36 GMT, Joe Wang <jo...@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
