RFR: JDK-8234682: The order of @param in the generated docs should match the method signature

[Roger Riggs]

On Wed, 12 Jan 2022 08:40:08 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> Please review a change in how documentation from `@param` tags is generated. 
> 
> The old code generates parameter documentation for each `@param` in the order in which the tags occur in the comment, then adds documentation from inherited `@param` tags for undocumented parameters. 
> 
> The new code always generates documentation in the order in which actual parameters are declared in the code, using local or inherited `@param` tags as appropriate. Any `@param` tags that do not have a matching parameter are added afterwards.
> 
> Note that `@param` is not just used for parameters of executable members but also type parameters and record components. The second commit of this PR fixes a `ClassCastException` for these uses that was caused by the first commit and adds a few tests for it.

It would be helpful if the order of the @param tags in the source was matched the declaration.
Can a warning be generated if the @param tags are out of order?

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

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