RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v5]

[Pavel Rappo]

On Mon, 6 Jun 2022 20:19:09 GMT, Jonathan Gibbons <jjg at 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