jdk
jdk copied to clipboard
openjdk
8305406: Add @spec tags in java.base/java.* (part 2)
Please review a doc update to add @spec tags to crypto and security APIs in java.base.
This was authored and proposed as #13336 by @jonathan-gibbons as part of an effort to add @spec tags and an external specifications page to API documentation. The original PR was reviewed and approved, yet for some reason it was never integrated.
Since I couldn't reopen Jon's PR I created a new pull request based the original commits. They still apply cleanly, and I made sure all links are still valid and working. I added a commit to update the copyright header dates.
Progress
- [ ] Change must be properly reviewed (1 review required, with at least 1 Reviewer)
- [x] Change must not contain extraneous whitespace
- [x] Commit message must refer to an issue
Issue
- JDK-8305406: Add @spec tags in java.base/java.* (part 2) (Enhancement - P3)
Reviewing
Using git
Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/21326/head:pull/21326
$ git checkout pull/21326
Update a local copy of the PR:
$ git checkout pull/21326
$ git pull https://git.openjdk.org/jdk.git pull/21326/head
Using Skara CLI tools
Checkout this PR locally:
$ git pr checkout 21326
View PR using the GUI difftool:
$ git pr show -t 21326
Using diff file
Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/21326.diff
Webrev
:wave: Welcome back hannesw! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.
![bridgekeeper[bot] avatar](https://avatars.githubusercontent.com/u/41768318?v=4 "Published by a pub.dev verified publisher"){kind=small}
@hns This change now passes all automated pre-integration checks.
ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.
After integration, the commit message for the final commit will be:
8305406: Add @spec tags in java.base/java.* (part 2)
Co-authored-by: Daniel Jeliński <[email protected]>
Co-authored-by: Hannes Wallnöfer <[email protected]>
Reviewed-by: valeriep
You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.
At the time when this comment was updated there had been 334 new commits pushed to the master branch:
- f1a9a8d25b2e1f9b5dbe8719abb66ec4cd9057dc: 8342902: Deduplication of acquire calls in BindingSpecializer causes escape-analyisis failure
- f1cc890ddfe2e472cf786856dc7d01645f61b054: 8343086: [BACKOUT] JDK-8295269 G1: Improve slow startup due to predictor initialization
- 36d71735e3554264e8d17f7e0e72999ac639e398: 8339289: Enhance Attach API to support arbitrary length arguments - Windows
- ff165f9f0cf519144d7361b766bcce53d04c518e: 8342934: TYPE_USE annotations printed with error causing "," in toString output
- 0853aee3b377cf9f17340a85f600651db42e6999: 8338426: Test java/nio/channels/Selector/WakeupNow.java failed
- c202a2f7b231152136bd8960c55e43bc96cf1eb9: 8295269: G1: Improve slow startup due to predictor initialization
- 5cbd578fbe9df4f68ab21bf764208ad4f67443f6: 8342930: New tests from JDK-8335912 are failing
- 1e35da8d3341ed1af266e5b59aa90bfcfae6576a: 8343063: RISC-V: remove redundant reg copy in generate_resolve_blob
- 4f8f395e2bb692148e2b891198f28a579749dd6d: 8343060: RISC-V: enable TestFloat16VectorConvChain for riscv
- a9eb50a2d8341b454c55c2f56446775c497ddde9: 8342953: RISC-V: Fix definition of RISCV_HWPROBE_EXT_ZVFHMIN
- ... and 324 more: https://git.openjdk.org/jdk/compare/7d524d7e378430afb3a262e8fe544bd1be22748c...master
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.
➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.
@hns The following labels will be automatically applied to this pull request:
netsecurity
When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.
One of the reasons for adding the javadoc @spec tag is to create an "External Specifications" page in API docs. This feature is currently disabled in OpenJDK build (because of incomplete @spec tags in libraries), but I have uploaded a bundle of API docs with this PR and the "External Specifications" page enabled. This should make this PR somewhat easier to review as the spec URLs can be reviewed directly in the browser.
Is "https://tools.ietf.org/html/rfc8103" considered external spec? It is mentioned in com.sun.crypto.provider.ChaCha20Poly1305Parameters class but not covered in this PR. Is there any additional condition for an external reference to be included? How about an external reference to a section of a specification? E.g. http://www.w3.org/TR/xmlenc-core/#sec-Alg-SymmetricKeyWrap in com.sun.crypto.provider.DESedeWrapCipher class which is also not covered by this PR.
Is "https://tools.ietf.org/html/rfc8103" considered external spec? It is mentioned in com.sun.crypto.provider.ChaCha20Poly1305Parameters class but not covered in this PR. Is there any additional condition for an external reference to be included? How about an external reference to a section of a specification? E.g. http://www.w3.org/TR/xmlenc-core/#sec-Alg-SymmetricKeyWrap in com.sun.crypto.provider.DESedeWrapCipher class which is also not covered by this PR.
Valerie,
The intent of @spec is to include any external specification that is referenced in the public API documentation. As a rule of thumb, an external specification is any one given by name and/or an absolute URL. Note, not all references with absolute URLs are specifications. Some may be references to additional non-normative sources such as guides and similar materials.
This PR, and others that have preceded it, are mechanically derived by examining @see and {@link} tags in public API documentation. Once this initial work has been completed, it will be up to individual component teams to update any @spec tags in their area, either adding new tags, or modifying/updating the URLs of existing tags.
@valeriepeng I added two more @spec tags as suggested by your feedback (the ones I felt confident about).
I'm also uploading new API docs with the "External Specifications" page here: https://cr.openjdk.org/~hannesw/8305406/api.01/external-specs.html
/author set @jonathan-gibbons /contributor add @djelinski /contributor add @hns
@hns
Setting overriding author to Jonathan Gibbons <[email protected]>. When this pull request is integrated, the overriding author will be used in the commit.
Is "https://tools.ietf.org/html/rfc8103" considered external spec? It is mentioned in com.sun.crypto.provider.ChaCha20Poly1305Parameters class but not covered in this PR. Is there any additional condition for an external reference to be included? How about an external reference to a section of a specification? E.g. http://www.w3.org/TR/xmlenc-core/#sec-Alg-SymmetricKeyWrap in com.sun.crypto.provider.DESedeWrapCipher class which is also not covered by this PR.
Valerie,
The intent of
@specis to include any external specification that is referenced in the public API documentation. As a rule of thumb, an external specification is any one given by name and/or an absolute URL. Note, not all references with absolute URLs are specifications. Some may be references to additional non-normative sources such as guides and similar materials.This PR, and others that have preceded it, are mechanically derived by examining
@seeand{@link}tags in public API documentation. Once this initial work has been completed, it will be up to individual component teams to update any@spectags in their area, either adding new tags, or modifying/updating the URLs of existing tags.
I see. Thanks for the clarification.
Going to push as commit 873f8a696fa45c7d94a164be20cf3c797ce7f2a6.
Since your change was applied there have been 335 commits pushed to the master branch:
- 1476f6c47511ad9dceda3633776ace3ee353d7ed: 8343030: RISC-V: Small assembler cleanups
- f1a9a8d25b2e1f9b5dbe8719abb66ec4cd9057dc: 8342902: Deduplication of acquire calls in BindingSpecializer causes escape-analyisis failure
- f1cc890ddfe2e472cf786856dc7d01645f61b054: 8343086: [BACKOUT] JDK-8295269 G1: Improve slow startup due to predictor initialization
- 36d71735e3554264e8d17f7e0e72999ac639e398: 8339289: Enhance Attach API to support arbitrary length arguments - Windows
- ff165f9f0cf519144d7361b766bcce53d04c518e: 8342934: TYPE_USE annotations printed with error causing "," in toString output
- 0853aee3b377cf9f17340a85f600651db42e6999: 8338426: Test java/nio/channels/Selector/WakeupNow.java failed
- c202a2f7b231152136bd8960c55e43bc96cf1eb9: 8295269: G1: Improve slow startup due to predictor initialization
- 5cbd578fbe9df4f68ab21bf764208ad4f67443f6: 8342930: New tests from JDK-8335912 are failing
- 1e35da8d3341ed1af266e5b59aa90bfcfae6576a: 8343063: RISC-V: remove redundant reg copy in generate_resolve_blob
- 4f8f395e2bb692148e2b891198f28a579749dd6d: 8343060: RISC-V: enable TestFloat16VectorConvChain for riscv
- ... and 325 more: https://git.openjdk.org/jdk/compare/7d524d7e378430afb3a262e8fe544bd1be22748c...master
Your commit was automatically rebased without conflicts.
@hns Pushed as commit 873f8a696fa45c7d94a164be20cf3c797ce7f2a6.
:bulb: You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.