Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Fri, 31 Mar 2023 16:28:14 GMT, Sean Mullan wrote: > I didn't see any changes to security APIs - are they coming in a follow-on > issue? Yes, this is _Add `@spec` tags in java.base/java.* (part 1)_ The rest of `java.base` will be in part 2. - PR Comment: https://git.openjdk.org/jdk/pull/13248#issuecomment-1492670942
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Fri, 31 Mar 2023 10:45:39 GMT, Lance Andersen wrote: > > Hi Jon, > > This looks fine. I was wondering if we should do the same for java.util.zip > > and the PKWare Zip Spec or where java.sql references the JDBC Spec? > > Well, I must need coffee this morning as obviously JDBC is in the java.sql > module, not java.base So scratch that comment ;-) The other modules will be done in due course. - PR Comment: https://git.openjdk.org/jdk/pull/13248#issuecomment-1492417414
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Fri, 31 Mar 2023 17:14:01 GMT, Iris Clark wrote: >> Jonathan Gibbons has updated the pull request incrementally with one >> additional commit since the last revision: >> >> address review feedback > > 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. The `@spec` tag should point to the root, but we should not remove more specific references to within the spec. I will review places where `@see` has been removed/replaced. - PR Review Comment: https://git.openjdk.org/jdk/pull/13248#discussion_r1154774688
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Thu, 30 Mar 2023 20:45:08 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: > > address review feedback LGTM - Marked as reviewed by mchung (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/13248#pullrequestreview-1367320601
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Thu, 30 Mar 2023 20:45:08 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: > > 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
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Thu, 30 Mar 2023 20:45:08 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: > > address review feedback I didn't see any changes to security APIs - are they coming in a follow-on issue? - PR Comment: https://git.openjdk.org/jdk/pull/13248#issuecomment-1492236091
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Fri, 31 Mar 2023 10:33:50 GMT, Lance Andersen wrote: > Hi Jon, > > This looks fine. I was wondering if we should do the same for java.util.zip > and the PKWare Zip Spec or where java.sql references the JDBC Spec? Well, I must need coffee this morning as obviously JDBC is in the java.sql module, not java.base So scratch that comment ;-) - PR Comment: https://git.openjdk.org/jdk/pull/13248#issuecomment-1491723581
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Thu, 30 Mar 2023 20:45:08 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: > > address review feedback I had a look at the java.net part and it looks reasonable. - Marked as reviewed by dfuchs (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/13248#pullrequestreview-1366700592
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Thu, 30 Mar 2023 20:45:08 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: > > address review feedback Hi Jon, This looks fine. I was wondering if we should do the same for java.util.zip and the PKWare Zip Spec or where java.sql references the JDBC Spec? - Marked as reviewed by lancea (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/13248#pullrequestreview-1366691673
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Thu, 30 Mar 2023 20:45:08 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: > > address review feedback Marked as reviewed by alanb (Reviewer). - PR Review: https://git.openjdk.org/jdk/pull/13248#pullrequestreview-1366677936
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Thu, 30 Mar 2023 20:28:52 GMT, Jonathan Gibbons wrote: >> 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 ``. > > 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. Leave it in for now and we can look at it again when the external spec page is in place. My comment is mostly that it will look a bit strange to link to this method because it's text in an implNote rather than spec. - PR Review Comment: https://git.openjdk.org/jdk/pull/13248#discussion_r1154302925
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Thu, 30 Mar 2023 20:45:08 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: > > address review feedback Good to see these changes. - Marked as reviewed by darcy (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/13248#pullrequestreview-1366237224
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
On Thu, 30 Mar 2023 20:45:08 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: > > address review feedback Changes in i18n-related classes look good to me. - Marked as reviewed by naoto (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/13248#pullrequestreview-1366032864
Re: RFR: JDK-8305206: Add @spec tags in java.base/java.* (part 1) [v2]
> 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 - Changes: - all: https://git.openjdk.org/jdk/pull/13248/files - new: https://git.openjdk.org/jdk/pull/13248/files/3e1102a9..096a4188 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=13248=01 - incr: https://webrevs.openjdk.org/?repo=jdk=13248=00-01 Stats: 2 lines in 1 file changed: 1 ins; 0 del; 1 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
