Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v3]
On Fri, 31 Mar 2023 22:07:26 GMT, Jonathan Gibbons 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: > > revert removing @see tags where the URL was not the same as the @spec URL Marked as reviewed by iris (Reviewer). - PR Review: https://git.openjdk.org/jdk/pull/13248#pullrequestreview-1367798667
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v3]
> 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: revert removing @see tags where the URL was not the same as the @spec URL - Changes: - all: https://git.openjdk.org/jdk/pull/13248/files - new: https://git.openjdk.org/jdk/pull/13248/files/096a4188..7f64cc32 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=13248=02 - incr: https://webrevs.openjdk.org/?repo=jdk=13248=01-02 Stats: 12 lines in 4 files changed: 12 ins; 0 del; 0 mod Patch: https://git.openjdk.org/jdk/pull/13248.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/13248/head:pull/13248 PR: https://git.openjdk.org/jdk/pull/13248
