On Mon, 6 Jun 2022 20:19:09 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
>> Pavel Rappo has updated the pull request with a new target base due to a >> merge or a rebase. The pull request now contains 35 commits: >> >> - Merge branch 'master' into 8287333 >> >> It's two days before RDP1, the codebase changes quickly. This merge is to >> keep up with it. >> - Address feedback >> >> Also removes unneeded import. >> - Merge branch 'master' into 8287333 >> >> This resolves a conflict in ParamTaglet. >> - Clean up if-branch >> - Remove upper-bounded wildcard >> >> This change simplifies code without any disadvantages: >> >> * Those `List<? extends XTree>` are read-only >> * An argument of the `List<XTree>` type can still be passed to a >> `List<? extends XTree>` parameter >> - Simplify inheritThrowsDocumentation >> - Reuse more specific variable >> - Merge branch 'master' into 8287333 >> - Incremental update >> >> - Renames local variables and method parameters >> - Improves comments >> - Removes debug leftovers >> - Update top-level doc comment >> - ... and 25 more: >> https://git.openjdk.java.net/jdk/compare/f1dd559e...9c91efb0 > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java > line 94: > >> 92: ? ee.getTypeParameters() >> 93: : ee.getParameters(); >> 94: String target = ch.getParameterName((ParamTree) >> input.docTreeInfo.docTree()); > > I'm guessing that it is not practical to have DocTreeInfo be generic in the > DocTree field. > > An alternative coding style here is to pass in an argument for the expected > return type, as in > > String target = > ch.getParameterName(input.docTreeInfo.docTree(ParamTree.class)); That relates to the plan of dealing with `Input.tagId` that we discussed (chronologically) earlier in this PR. Since it's second time we touch this area, here are some bits of that plan. Rather than generify `DocTreeInfo` and, therefore `DocFinder.Input`, we could first note a few things about `Input`: * `tagId` and `docTreeInfo` are used only by `ParamTaglet` and `ThrowsTaglet` * `ParamTaglet` and `ThrowsTaglet` use `tagId` and `docTreeInfo` as poor surrogates for more specific types: * `tagId` should be `Integer` for `ParamTaglet` and `TypeMirror` for `ThrowsTaglet` * `Input.docTreeInfo.docTree` should be of different subtypes of `DocTree` (as you note) * `isTypeVariableParamTag` is used only by `ParamTaglet` Similarly, we note this for `Output`: `tagList` is only used by `ThrowsTaglet`. What does it tell us? Well, to me it sounds like `Input` and `Output` are nonspecific bags of values used by all inheritable tags. That needlessly clutters `DocFinder`, which does not use *any* of those fields. To declutter `DocFinder` and isolate inheritable taglets from each other, a subclass of inheritable taglet should instead use its own subclasses of `Input` and `Output` to pass all the necessary inheritance information. I started working on that in JDK 19, didn't have enough time to finish. I plan to continue working on that in JDK 20, where the result will hopefully land. ------------- PR: https://git.openjdk.java.net/jdk/pull/8886
