Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

8285400: Add '@apiNote' to the APIs defined in Java SE 8 MR 3 #7

Closed
wants to merge 3 commits into from

Conversation

poonamparhar
Copy link
Member

@poonamparhar poonamparhar commented Apr 25, 2022

This change adds "apiNote This method is defined in Java SE 8 Maintenance Release 3." to the doc comments of the new APIs added with the following changesets in Java SE MR3 :

  1. https://hg.openjdk.java.net/jdk8u/jdk8u41/jdk/rev/b26b096d4c89
  2. https://hg.openjdk.java.net/jdk8u/jdk8u41/jdk/rev/6bada58189de

Progress

  • Change must not contain extraneous whitespace
  • Commit message must refer to an issue
  • Change must be properly reviewed

Issue

Reviewers

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk8u-ri pull/7/head:pull/7
$ git checkout pull/7

Update a local copy of the PR:
$ git checkout pull/7
$ git pull https://git.openjdk.java.net/jdk8u-ri pull/7/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 7

View PR using the GUI difftool:
$ git pr show -t 7

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk8u-ri/pull/7.diff

@bridgekeeper
Copy link

bridgekeeper bot commented Apr 25, 2022

👋 Welcome back poonam! 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.

@openjdk openjdk bot added the rfr Pull request is ready for review label Apr 25, 2022
@mlbridge
Copy link

mlbridge bot commented Apr 25, 2022

Webrevs

@valeriepeng
Copy link

valeriepeng commented Apr 25, 2022

How about the SHA512_224 and SHA512_256 constants in java/security/spec/MGF1ParameterSpec.java? Should add the since and apiNot javadoc tags as well?

Copy link

@bradfordwetmore bradfordwetmore left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the word choice confirmed/approved, or still up for editing? Seems like this should be in past tense, IMHO.

This method was added in Java SE 8 Maintenance Release 3.

@bradfordwetmore
Copy link

Shouldn't the copyright dates be updated to 2022? These are significant changes to the files involved.

@@ -584,6 +584,7 @@ public final void initVerify(Certificate certificate)
* supposed to be used for digital signatures, an
* {@code InvalidKeyException} is thrown.
*
* @apiNote This method is defined in Java SE 8 Maintenance Release 3.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, there are other pkg private methods added in the maintenance release which do not have the @since javadoc tag. For consistency sake, maybe removing the @since tag here and no need to add @apiNote then?

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I apparently let this slip through, this @since should not have been there. Please remove it and the @apiNote. Thanks.

@valeriepeng
Copy link

How about the SHA512_224 and SHA512_256 constants in java/security/spec/MGF1ParameterSpec.java? Should add the since and apiNot javadoc tags as well?

The PSSParameterSpec.TRAILER_FIELD_BC needs the @apiNote too?

* @apiNote
* This method should be called by TLS server applications before the TLS
* @apiNote This method is defined in Java SE 8 Maintenance Release 3.
*
Copy link

@bradfordwetmore bradfordwetmore Apr 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMHO, this needs a separator here to separate the existing API from the addition. Or maybe a second @apiNote? It currently renders as this:

API Note:
This method is defined in Java SE 8 Maintenance Release 3. This method 
should be called by TLS server application...

Copy link
Member

@mlchung mlchung Apr 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest using <p> to start with a new paragraph.

Copy link

@bradfordwetmore bradfordwetmore Apr 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm guessing @mlchung meant <p>. Her suggestion didn't render correctly.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's what I meant. I updated the formatting of my comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI: a second @apiNote does not render correctly, suggest using

which I've verified does.

API Note:
This method is defined in Java SE 8 Maintenance Release 3.

This method should be called by TLS server...

@@ -760,8 +762,9 @@ public String getHandshakeApplicationProtocol() {
* });
* }</pre>
*
* @apiNote
* This method should be called by TLS server applications before the TLS
* @apiNote This method is defined in Java SE 8 Maintenance Release 3.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same concern here about either a second @apiNote or a separator.

@bradfordwetmore
Copy link

Same concern as @valeriepeng on both the MGF1ParameterSpec and PSSParameterSpec field omissions. We did add a @since in PSSParameterSpec, but not MGF1ParameterSpec.

@poonamparhar
Copy link
Member Author

@bradfordwetmore @valeriepeng I have addressed all the concerns and have updated the PR. Please take a look.

Copy link

@bradfordwetmore bradfordwetmore left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copyright date updates not complete.

Copy link
Member

@mlchung mlchung left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change looks good to me. Thanks for doing this update.

Can you file a JBS issue to fix in the mainline to add back @since in the constants in MGF1ParameterSpec class? Thanks.

@bradfordwetmore
Copy link

This change looks good to me. Thanks for doing this update.

Can you file a JBS issue to fix in the mainline to add back @since in the constants in MGF1ParameterSpec class? Thanks.

Good idea, thanks @mlchung!

Copy link

@bradfordwetmore bradfordwetmore left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

@openjdk
Copy link

openjdk bot commented Apr 29, 2022

@poonamparhar This change now passes all automated pre-integration checks.

After integration, the commit message for the final commit will be:

8285400: Add '@apiNote' to the APIs defined in Java SE 8 MR 3

Reviewed-by: wetmore, mchung, 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 4 new commits pushed to the master branch:

  • 58ec25d: 8201793: (ref) Reference object should not support cloning
  • 330d63d: 8175797: (ref) Reference::enqueue method should clear the reference object before enqueuing
  • ad6cdea: 8071507: (ref) Clear phantom reference as soft and weak references do
  • d63ed0a: 8284907: Compact profiles build fails with GNU make 4

Please see this link for an up-to-date comparison between the source branch of this pull request and the master branch.
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.

@openjdk openjdk bot added the ready Pull request is ready to be integrated label Apr 29, 2022
@poonamparhar
Copy link
Member Author

/integrate

@openjdk
Copy link

openjdk bot commented Apr 29, 2022

Going to push as commit 3740d05.
Since your change was applied there have been 4 commits pushed to the master branch:

  • 58ec25d: 8201793: (ref) Reference object should not support cloning
  • 330d63d: 8175797: (ref) Reference::enqueue method should clear the reference object before enqueuing
  • ad6cdea: 8071507: (ref) Clear phantom reference as soft and weak references do
  • d63ed0a: 8284907: Compact profiles build fails with GNU make 4

Your commit was automatically rebased without conflicts.

@openjdk openjdk bot added the integrated Pull request has been integrated label Apr 29, 2022
@openjdk openjdk bot closed this Apr 29, 2022
@openjdk openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Apr 29, 2022
@openjdk
Copy link

openjdk bot commented Apr 29, 2022

@poonamparhar Pushed as commit 3740d05.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
integrated Pull request has been integrated
4 participants