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

[Pavel Rappo]

On Fri, 3 Jun 2022 11:34:52 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only copies one instance of the specified exception.
>
> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 28 additional commits since the last revision:
> 
>  - 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
>  - Remove dead condition
>    
>    tagsMap is never empty by the time that check is reached: a mapping being put into it 3 lines above the check.
>  - Remove emptiness check
>    
>    Why bother in this case? It only wastes indentation.
>  - Remove comments
>    
>    Two very similar comments to a private, self-documenting method is a bit too much.
>  - Use consistent order
>    
>    Use "decalred" then "instantiated".
>  - Rename and clarify
>    
>     - Renames a parameter to the throwsTagsOutput method
>     - Widens the type of a local variable
>  - ... and 18 more: https://git.openjdk.java.net/jdk/compare/51a35060...7f1d9324

Please review this strictly cleanup change, which allowed to better prepare for JDK-6509045 and uncovered a few latent but major issues with `ThrowsTaglet`, which should be addressed early in JDK 20.

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

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