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

[Pavel Rappo]

On Mon, 6 Jun 2022 20:39:10 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 147:
> 
>> 145:     /**
>> 146:      * Returns a {@code Content} representation of a list of {@code ParamTree}.
>> 147:      * Tries to inherit the param tags that are missing.
> 
> mild grumble to see information being removed, even it is obvious to you.

I can revert that, if you want.

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

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