On Thu, 30 Mar 2023 19:42:33 GMT, Alan Bateman <al...@openjdk.org> wrote:
>> Please review a change to add `@spec` tags (and remove some equivalent >> `@see` tags) to the main "core-libs" packages in `java.base` module. >> >> This is similar to, and a subset of, PR #11073. That PR was withdrawn, and >> based on the ensuing discussion and suggestion, is now being handled with a >> series of PRs for various separate parts of the system. Follow-up PRs will >> be provided for the rest of `java.base`, for `java.desktop`, and for XML >> APIs. The "LangTools" modules have already been updated. The "External >> Specifications" page has been temporarily [disabled][] until this work is >> complete. >> >> While the primary content of the change was automated, I've manually >> adjusted the formatting, to break long lines. >> >> It is clear there is significant inconsistency in the ordering of block tags >> in doc comment. We might want to (separately) consider normalizing the >> order of the tags, perhaps according to the order defined for the tags in >> the generated output, as given [here][] >> >> [here]: >> https://github.com/openjdk/jdk/blob/83cf28f99639d80e62c4031c4c9752460de5f36c/make/Docs.gmk#L68 >> [disabled]: >> https://github.com/openjdk/jdk/blob/83cf28f99639d80e62c4031c4c9752460de5f36c/make/Docs.gmk#L115 > > src/java.base/share/classes/java/lang/Thread.java line 1960: > >> 1958: * thread. >> 1959: * >> 1960: * @spec jni/index.html Java Native Interface Specification > > The link to the JNI spec in this method is from implNote so I'm wondering if > the spec link is needed here. Right now, the tag is added for any declaration whose comment contains a reference to an external spec (i.e. with `<a href-....>`. When we enable the "External Specifications" page, it will contain a link back to this page as part of the cross-reference info, which seems useful. That being said, if you feel strongly the tag should not be added here, I can remove it. > src/java.base/share/classes/java/nio/file/Files.java line 1724: > >> 1722: * >> 1723: * @spec https://www.rfc-editor.org/info/rfc2045 >> 1724: * RFC 2045: RFC 2045: Multipurpose Internet Mail Extensions >> (MIME) Part One: Format of Internet Message Bodies > > Maybe this one can be put on two lines to avoid the wrapping when looking at > is side-by-side. Fixed. There was also a stutter-bug with a double "RFC 2045: RFC 2045:" which I have also fixed. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/13248#discussion_r1153755656 PR Review Comment: https://git.openjdk.org/jdk/pull/13248#discussion_r1153756945
