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

[Hannes Wallnöfer]

On Thu, 13 Jan 2022 15:30:59 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Out of curiosity, how much of a churn does this PR introduce into the generated JDK API documentation? In any case, we should check it, to make sure that nothing surprising comes up.

That's a very good question! Turns out there are more than 50 classes in JDK that contain `@param` tags in wrong order. For instance, there is a [Collectors.groupingBy][1] method that gets both type and method parameter order wrong. I'm surprised not more of these get reported as bugs because I think they're quite confusing. 

[1]: https://download.java.net/java/early_access/jdk18/docs/api/java.base/java/util/stream/Collectors.html#groupingBy(java.util.function.Function,java.util.function.Supplier,java.util.stream.Collector)

I checked a few cases against the documentation generated with this PR and the it fixes the problem.

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

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