-
Notifications
You must be signed in to change notification settings - Fork 58
8067757: Incorrect HTML generation for copied javadoc with multiple @throws tags #95
Conversation
👋 Welcome back prappo! A progress list of the required criteria for merging this PR into |
@pavelrappo The following label 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 list. If you would like to change these labels, use the /label pull request command. |
@@ -504,7 +504,7 @@ public Content throwsTagOutput(Element element, ThrowsTree throwsTag, TypeMirror | |||
excName = htmlWriter.getLink(new HtmlLinkInfo(configuration, HtmlLinkInfo.Kind.MEMBER, | |||
substituteType)); | |||
} else if (exception == null) { | |||
excName = new RawHtml(ch.getExceptionName(throwsTag).toString()); | |||
excName = new RawHtml(throwsTag.getExceptionName().toString()); |
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.
It's not your code or edit here, but I'll mention it anyway ...
We should be on the lookout for unnecessary use of RawHtml
. It looks like this is a candidate for a (later) cleanup to use just Text
, not RawHtml
.
public ReferenceTree getExceptionName(ThrowsTree tt) { | ||
return tt.getExceptionName(); | ||
} | ||
|
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.
Yes, this does seem a bit superfluous
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.
Nice.
This time, the individual change sets helped.
Thanks for working on the doc comments, in the places you did; they do help.
@pavelrappo 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 5 new commits pushed to the
Please see this link for an up-to-date comparison between the source branch of this pull request and the ➡️ To integrate this PR with the above commit message to the |
/integrate |
Going to push as commit f640fc5.
Your commit was automatically rebased without conflicts. |
@pavelrappo Pushed as commit f640fc5. 💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored. |
Please review this PR for JDK 19.
This PR fixes JDK-8067757. To understand what JDK-8067757 is about, you first need to understand how javadoc documents the fact that such and such exceptions are thrown by a constructor or method.
If a constructor or method declaration indicates thrown exceptions, javadoc creates the "Throws:" section in that declaration documentation. Here's the algorithm which javadoc uses to fill in that section:
@throws
tag that is directly present on the declaration, add an entry to the section.throws
clause for which there were no@throws
tags found in step 1, try to inherit@throws
tags from the overridden methods found as per Method Comments Algorithm1.throws
clause (i.e. the exceptions for which documentation could neither be found in step 1, nor inherited in step 2), add an entry that mentions the exception but has no description.The problem that JDK-8067757 is concerned with is that if an exception is documented using multiple
@throws
tags, only one of these tags will be inherited in step 2.While fixing this issue I discovered an unpleasant interference with JDK-49474552 and fixed it.
Looking ahead, JDK-65090453 is about a similar problem that happens in step 1 in the presence of
{@inheritDoc}
. I'm also planning to fix JDK-6509045 in JDK 19.Progress
Issue
Reviewers
Reviewing
Using
git
Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk19 pull/95/head:pull/95
$ git checkout pull/95
Update a local copy of the PR:
$ git checkout pull/95
$ git pull https://git.openjdk.org/jdk19 pull/95/head
Using Skara CLI tools
Checkout this PR locally:
$ git pr checkout 95
View PR using the GUI difftool:
$ git pr show -t 95
Using diff file
Download this PR as a diff file:
https://git.openjdk.org/jdk19/pull/95.diff
Footnotes
https://docs.oracle.com/en/java/javase/18/docs/specs/javadoc/doc-comment-spec.html#method-comments-algorithm ↩
https://bugs.openjdk.org/browse/JDK-4947455 ↩
https://bugs.openjdk.org/browse/JDK-6509045 ↩