-
Notifications
You must be signed in to change notification settings - Fork 5.8k
8330954: since-checker - Fix remaining @ since tags in java.base #18954
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
Conversation
👋 Welcome back nizarbenalla! A progress list of the required criteria for merging this PR into |
@nizarbenalla 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:
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 73 new commits pushed to the
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. As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@liach, @naotoj) but any other Committer may sponsor as well. ➡️ To flag this PR as ready for integration with the above commit message, type |
@nizarbenalla The following labels will be automatically applied to this pull request:
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. |
I think your changes mostly group in these categories:
|
src/java.base/share/classes/java/lang/classfile/ClassSignature.java
Outdated
Show resolved
Hide resolved
src/java.base/share/classes/java/lang/constant/MethodHandleDesc.java
Outdated
Show resolved
Hide resolved
|
For case 1 I mentioned, the new since tags in |
Recent [offline] discussions have showed that dealing with |
Please consider this scenario where class A extends B, both from earlier versions, and there's For your convenience, I will reiterate with the javadoc output API specification instead of just the source code. These are most likely caused by bugs in your analyais tool:
All other changes look correct. |
|
Those overriding methods don't even appear on the javadoc output. If you go to search for Also have you looked at the output documentation? Without the |
FYI you can generate the documentation with I don't want to reiterate again, but if a method is declared so: /**
* Class One.
*
* @since 42
*/
public class One {
/**
* Method.
*
* @since 48
*/
public void method() {}
}
/**
* Class Two.
*
* @since 42
*/
public class Two extends One {
@Override
public void method() {}
} The generated docs for What's wrong with you that you ask |
For overriding methods we don't look into the supertype because that's what |
I'm sorry, you have always mentioned "match the javadoc rules" "javadoc doesn't look into supertype" "go against current behavior", but there is no problem with these
We indeed don't because we treat it as if it does not exist, and then the current docs are right. Please, just take a look at the javadoc output once and reach your own conclusion. |
If possible, I wish the others who joined the offline discussion can take part here. It seems you have some trouble understanding that overriding methods without explicit documentation are ignored by javadoc, and this ignorance makes the |
When I said "For overriding methods we don't look into the supertype" I meant my checker tool doesn't do that.
This is still a Draft PR, I meant to add the Others can join the discussion if they want, I'll let them know on monday but you might just get the same answer. For now the decision is that the every time an overload like the ones in this Draft PR is added, we would need to add explicit javadoc comment as we can't infer the |
* @throws IllegalArgumentException {@inheritDoc} | ||
* @throws IOException {@inheritDoc} | ||
* @throws OutOfMemoryError {@inheritDoc} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Re: inheriting unchecked exception documentation here and elsewhere in this PR
This PR's title suggests that the PR has nothing to do with exception documentation. If you feel that it should be addressed, please file a separate bug and move these changes there.
FWIW, I agree that @throws ... {@inheritDoc}
for such exceptions are at least worth being considered. It's a common misconception that all exception documentation is inherited automatically.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is because the tool from #18934 has no easy way to fetch the doc comment from a superclass/superinterface overridden method when this class only has a plain override. Javadoc handles this in complex logic in VisibleMemberTable
; it's hard for other clients to try to emulate the behavior of doc finding, and the tool just incorrectly assumes such methods (what I have been talking about before) are reusing @since
from the class docs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pavel, can I simply change the PR/issue title to be more descriptive?
As I want to include the the inherit doc because of the unchecked exceptions, rather than clean this up in a different PR
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pavel, can I simply change the PR/issue title to be more descriptive? As I want to include the the inherit doc because of the unchecked exceptions, rather than clean this up in a different PR
I suggest dropping all the changes that are irrelevant to @since
from this PR, unless you have PRs with similar mixed changes integrated. As far as I know, @since
is not a normative part of documentation, whereas @throws
is. So the latter is a bigger change and would require more scrutiny and more area experts during review.
In the future, we might want to have yet another aid/tool: a "@throws
checker" that finds all overriding methods that do not declare some of the unchecked exceptions that the methods they override do.
This is not how I remember it. Unless written around,
and a couple of other methods that override that method:
Now, as far as the main description goes, the above three are equivalent, and the main description is inherited. While the third variant is arguably the most readable, its
In this case, the generated documentation would be as follows:
|
Thanks for the explanation @pavelrappo. Also I recall inheritDoc has weird interactions with block tags like user-defined |
@@ -1,5 +1,5 @@ | |||
/* | |||
* Copyright (c) 1998, 2023, Oracle and/or its affiliates. All rights reserved. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This diff is redundant but no-op. You should merge openjdk/jdk's master branch to your PR branch, so the diff displayed by GitHub is up-to-date and this will go away.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't want to merge or rebase on an active PR. It should get fixed once this is integrated.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure, this comment serves as a note to reviewers that these 2 header changes have been committed in other changes and thus can be safely ignored.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There is no harm in merging the upstream master, using git merge
, to bring your branch more up-to-date. And it can be helpful in cases like this where it might help reviewers avoid extraneous information. It is also recommended in other cases (e.g., a long-running PR where there is a lot of drift between the PR source branch and the upstream target branch).
Skara will squash all commits anyway when integrating so the results will be identical.
Btw, one thing you should not do is rebase a source branch of an active PR.
@since
tags in java.base
@since
tags in java.base
I disagree somewhat with the statements in the comments that the checker should follow the javadoc rules, whatever they are. The important thing is to decide what the rules for As a practical rule for deciding whether any declaration is new or not, imagine writing a test program that refers to the most specific form of the declaration. If that test program does not compile on JDK version N-1 and does compile on version N, then it warrants having Note, these rules are stated without reference to what Also, while the proposed new Since Checker should follow these rules when analysing declarations, it may go further when making suggestions to correct errors that it finds. For example, instead of simply saying No |
@since
tags in java.base
@@ -41,7 +41,10 @@ public sealed interface ClassSignature | |||
/** {@return the type parameters of this class} */ | |||
List<Signature.TypeParam> typeParameters(); | |||
|
|||
/** {@return the instantiation of the superclass in this signature} */ | |||
/** {@return the instantiation of the superclass in this signature} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/** {@return the instantiation of the superclass in this signature} | |
/** | |
* {@return the instantiation of the superclass in this signature} |
I think this is our preference if we have multi-line specs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed in 91df97f, Thanks.
/** | ||
* @since 23 | ||
*/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IIUC, this addition will add & inherit the javadoc from NumberFormat
, which is not the case before. The description for NumberFormat does not fit with ChoiceFormat. Probably that needs to be addressed with a different issue.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My review is for the ChoiceFormat class only. So asking for more Reviews for other area
/reviewers 2 reviewer
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, I will leave this open for a few more days to let more people from the relevant areas review it.
/reviewers 2 reviewer |
OK, I look at other areas and I believe they are fine. |
Thank you Naoto for checking, and thanks Chen! /integrate |
@nizarbenalla |
/sponsor |
Going to push as commit f4fa35e.
Your commit was automatically rebased without conflicts. |
@liach @nizarbenalla Pushed as commit f4fa35e. 💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored. |
Please review this PR that aims to add all the remaining needed
@since
tags injava.base
, and group them into a single fix.This is related to #18934 and my work around the
@since
checker feature.Explicit
@since
tags are needed for some overriding methods for the purpose of the checker.I will only give the example with the
CompletableFuture
class but here is the before where the methods only appeared in "Methods declared in interface N"and after where the method has it's own javadoc, the main description is added and the
@since
tags are added as intended.I don't have an account on
https://cr.openjdk.org/
but I could host the generated docs somewhere if that is needed.TIA
Progress
Issue
Reviewers
Reviewing
Using
git
Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/18954/head:pull/18954
$ git checkout pull/18954
Update a local copy of the PR:
$ git checkout pull/18954
$ git pull https://git.openjdk.org/jdk.git pull/18954/head
Using Skara CLI tools
Checkout this PR locally:
$ git pr checkout 18954
View PR using the GUI difftool:
$ git pr show -t 18954
Using diff file
Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/18954.diff
Webrev
Link to Webrev Comment