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

[Jonathan Gibbons]

On Thu, 30 Mar 2023 19:42:33 GMT, Alan Bateman <alanb 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
>
> 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