JDK-8223358: Incorrect HTML structure in annotation pages #5746
Conversation
|
|
Webrevs
|
|
@hns This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration! |
|
(Minor: can you edit the initial long comment to fix spelling/typo: you use |
Generally, I think this is a bad idea and we should not do it. We are stuck with the existing naming in the reflection interfaces ( |
Good work. I agree that simplifying the classes is worthwhile. Previously, I've only looked at simplifying the writers, not the builders as well.
I'll ask the following questions, and then approve the review.
Should we go all the way and merge all annotation interface members into a single summary table? Is there benefit (other than, "they've always been separate") to keeping them separate? Should we merge them in the same way we're thinking to merge "Exceptions" and "Errors" into "Throwable"? Is the distinction somewhat similar to the minor distinction between void methods and methods that return a result?
The counter-argument is that you've done a lot of work to maintain the separation, and I don't want to unnecessarily discard that. Merging would probably make us have to look at what the merged table would look like, and how (or whether) to indicate the difference between required and optional members. But perhaps that detail just belongs down in the Details section.
| private final Kind kind; | ||
|
|
||
| /** | ||
| * Construct a new AnnotationTypeMemberWriterImpl for any kind of member. |
There was a problem hiding this comment.
I'll say it just the once, here, to avoid getting tedious. Consider using the 2nd person declarative form, "Constructs ...", in comments.
| /** | ||
| * Construct a new AnnotationTypeMemberWriterImpl for any kind of member. | ||
| * | ||
| * @param writer The writer for the class that the member belong to. |
| case REQUIRED -> memberSummaryTree.add(selectComment( | ||
| MarkerComments.START_OF_ANNOTATION_TYPE_REQUIRED_MEMBER_SUMMARY, | ||
| MarkerComments.START_OF_ANNOTATION_INTERFACE_REQUIRED_MEMBER_SUMMARY)); | ||
| case ANY -> throw new RuntimeException("unsupported member kind"); |
There was a problem hiding this comment.
consider using UnsupportedOperationException.
| switch (kind) { | ||
| case REQUIRED -> HtmlIds.ANNOTATION_TYPE_REQUIRED_ELEMENT_SUMMARY; | ||
| case OPTIONAL -> HtmlIds.ANNOTATION_TYPE_OPTIONAL_ELEMENT_SUMMARY; | ||
| case ANY -> throw new RuntimeException("unsupported member kind"); |
There was a problem hiding this comment.
Ditto consider UOE
| * | ||
| * <p><b>This is NOT part of any supported API. | ||
| * If you write code that depends on this, you do so at your own risk. | ||
| * This code and its internal interfaces are subject to change or | ||
| * deletion without notice.</b> | ||
| */ | ||
| public class AnnotationTypeRequiredMemberWriterImpl extends AbstractMemberWriter | ||
| implements AnnotationTypeRequiredMemberWriter, MemberSummaryWriter { | ||
| public class AnnotationTypeMemberWriterImpl extends AbstractMemberWriter |
There was a problem hiding this comment.
Git-grumble .... the changes in this file are big enough that Git will likely not track the rename correct ... end-git-grumble.
| switch (kind) { | ||
| case OPTIONAL -> memberSummaryTree.add(selectComment( | ||
| MarkerComments.START_OF_ANNOTATION_TYPE_OPTIONAL_MEMBER_SUMMARY, | ||
| MarkerComments.START_OF_ANNOTATION_INTERFACE_OPTIONAL_MEMBER_SUMMARY)); | ||
| case REQUIRED -> memberSummaryTree.add(selectComment( | ||
| MarkerComments.START_OF_ANNOTATION_TYPE_REQUIRED_MEMBER_SUMMARY, | ||
| MarkerComments.START_OF_ANNOTATION_INTERFACE_REQUIRED_MEMBER_SUMMARY)); | ||
| case ANY -> throw new RuntimeException("unsupported member kind"); | ||
| } |
There was a problem hiding this comment.
There are a number of switch (kind) .... statements. Would it help to put methods on the Kind enum?
There was a problem hiding this comment.
Maybe I don't see how to do it, but these methods would have to return quite a lot of constants from all over the place. I don't think putting these into fields would make things much nicer.
| @@ -256,7 +256,7 @@ protected Content getSummaryLink(Element e) { | |||
| case ENUM_CONSTANT -> new EnumConstantWriterImpl(this); | |||
| case RECORD_COMPONENT -> | |||
| throw new AssertionError("Record components are not supported by SummaryListWriter!"); | |||
| default -> new AnnotationTypeOptionalMemberWriterImpl(this, null); | |||
| default -> new AnnotationTypeMemberWriterImpl(this); | |||
There was a problem hiding this comment.
- I see it was always this way, but maybe it would be better to have an explicit
caselabel, and havedefaultthrow some sort ofnot handledexception, or else rely on javac doing a completeness check. - I'm surprised there isn't any parameter to the new constructor to indicate whether optional or required members are required.
There was a problem hiding this comment.
This one surprised me: Annotation elements do not have an ElementKind constant of their own, they use ElementKind.METHOD. This means the code above was never executed. It is also the reason annotation elements are linked as methods, including the empty parentheses. I'm not sure whether this is an oversight, a bug, or there is some intention behind it.
As for the code above I think it can be replaced with throwing a UnsupportedOperationException.
| @@ -115,4 +115,12 @@ | |||
| * @param annotationDocTree the content tree to which the tags will be added | |||
| */ | |||
| void addTags(Element member, Content annotationDocTree); | |||
|
|
|||
| /** | |||
| * Add the the default value documentation if the member has one. | |||
|
@hns This change now passes all automated pre-integration checks. 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 540 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.
|
|
/integrate |
|
Going to push as commit 055de6f.
Your commit was automatically rebased without conflicts. |
openjdk
bot
added
integrated
Please review a fix for a simple bug that somehow mushroomed into a major cleanup of the annotation member builder and writer code. I still think it is justified to do this as part of a bug fix since in my eyes it is the only reasonable way to fix the issue (lest we want to add more complex workarounds).
The problem is that currently we have two versions of each class used to generate annotation interface member documentation, one for required members and one for optional ones. However, only the summary tables are separated for these two kinds of members, while the details section uses one single list for both. This required coordination between the two builder classes to generate a single list without generating faulty (missing or duplicate) HTML. Obviously this workaround was flawed, since it avoided the duplicate headers but still generated duplicate lists and sections that should have been single elements.
Even for the summary section, the dual class setup seemed like overkill, since the two summary lists differ only in label/text content, and the only thing the optional member writer could do extra was to generate the default value info.
So the core of this change unifies the dual annotation member builder and writer classes into single classes. For the writer, this simply involves adding a few switch expressions to retrieve the correct text values based on the value of a new nested enum class. The builder class is now simply instantiated once instead of twice to generate the member details list, and it does it for all annotation members.
Since the builder also uses the writer to generate the unified details list, the new enum has 3 values:
OPTIONAL,REQUIREDandANY. I'm not totally happy with this setup, but IMO it is still better than before and I have added a few comments to explain the reasons behind it.To make retrieval of combined annotation members easier I added a new member kind to
VisibleMemberTableclass calledANNOTATION_TYPE_MEMBER. This also allowed me to simplify the subnavigation code inNavigation.javawhich also contained some ugly workarounds for annotation interfaces. In the process I also reestablished the old order of annotation member subnavigation links to put the required members link first - this had been changed inadvertently in JDK 17.The change in return type to the
getVisibleMembersmethods inVisibleMemberTablefromList<? extends Element>toList<Element>is from when I did manual list merging with these return values. I left it in because I think it potentially makes other future uses of these methods easier.I did a recursive diff on the generated documentation before and after the fix. Obviously the reversed annotation member subnav links are changed in every annotation page. Apart from that, the only annotation interface that contains both required and optional members in the JDK (and therefore the only one that is affected and benefits from this fix) is
javax.annotation.processing.Generatedin thejava.compilermodule.As a sidenote: I also considered changing the nomenclature of the whole bunch of classes from the obsolete "annotation type" to "annotation interface", but I think that would have been an even bigger disruption in the code. If we want to do this I would prefer to do it as a separate task.
Progress
Issue
Reviewers
Reviewing
Using
gitCheckout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/5746/head:pull/5746$ git checkout pull/5746Update a local copy of the PR:
$ git checkout pull/5746$ git pull https://git.openjdk.java.net/jdk pull/5746/headUsing Skara CLI tools
Checkout this PR locally:
$ git pr checkout 5746View PR using the GUI difftool:
$ git pr show -t 5746Using diff file
Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/5746.diff