RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1)

[Alan Bateman]

On Thu, 30 Mar 2023 17:24:11 GMT, Jonathan Gibbons <jjg at 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