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

[Iris Clark]

On Thu, 30 Mar 2023 20:45:08 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
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   address review feedback

Marked as reviewed by iris (Reviewer).

src/java.base/share/classes/java/io/ObjectOutputStream.java line 165:

> 163:  * @see java.io.Serializable
> 164:  * @see java.io.Externalizable
> 165:  * @since       1.1

Just confirming... The changes to the java.io classes for the Serialization Spec now all point to the index rather than particular chapters/sections. I'm assuming that's intentional so that when the top-level Spec page appears, there is a single entry for that specification.

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

PR Review: https://git.openjdk.org/jdk/pull/13248#pullrequestreview-1367309978
PR Review Comment: https://git.openjdk.org/jdk/pull/13248#discussion_r1154716150