On Thu, 30 Mar 2023 17:24:11 GMT, Jonathan Gibbons <j...@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 I skimmed through the changes and it looks quite good, much more workable than PR 11073. Do you have a proposed ordering with other tags? I expected it would go with @see but I see several where @spec is before @author, and @see after @author. I know it doesn't really matter. 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. 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. ------------- PR Review: https://git.openjdk.org/jdk/pull/13248#pullrequestreview-1365814487 PR Review Comment: https://git.openjdk.org/jdk/pull/13248#discussion_r1153715180 PR Review Comment: https://git.openjdk.org/jdk/pull/13248#discussion_r1153716361
