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

[Pavel Rappo]

On Mon, 6 Jun 2022 20:22:34 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 33 commits:
>> 
>>  - 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
>>  - Trivially re-order assignments
>>    
>>    ...for re-use
>>  - Reformat for clarity
>>    
>>    Now it's very clear that the "Throws:" section consists of three types of exceptions:
>>    
>>      1. documented
>>      2. inherited
>>      3. undocumented
>>  - ... and 23 more: https://git.openjdk.java.net/jdk/compare/ebc012ec...6bbe871b
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java line 70:
> 
>> 68:      */
>> 69:     private static Map<String, String> mapNameToPosition(Utils utils, List<? extends Element> params) {
>> 70:         Map<String, String> result = new HashMap<>();
> 
> Is there a reason not to change this to `Map<String, Integer>`

We could change it to `Integer` now, but it wouldn't help us much: the `DocFinder.Input.tagId` field, which that `Integer` is ultimately compared against, is of type `String`. To make it all the way, we would need to change `tagId` to `Integer` too. But that won't work because `tagId` is also used by `ThrowsTaglet` to store an exception class (or an exception type variable) name.

That said, I agree that we should change `String` to `Integer` there. Let's just not do it now as it requires deeper refactoring; I have a plan already and some implementation in the works.

-------------

PR: https://git.openjdk.java.net/jdk/pull/8886