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

[Pavel Rappo]

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.

test/langtools/jdk/javadoc/doclet/testParamTaglet/TestParamTaglet.java line 63:

> 61:                     </dl>""",
> 62:                 // Param tags that don't match with any real parameters.
> 63:                 // {@inherit} doc misuse does not cause doclet to throw exception.

Should we change this to `{@inheritDoc}`?

test/langtools/jdk/javadoc/doclet/testParamTaglet/pkg/C.java line 50:

> 48:      * @param b another duplicate
> 49:      */
> 50:     public void unorderedParams(int i, double d, boolean b) {}

Consider adding `@Override` to this method and to `nonMatchingParams`.

test/langtools/jdk/javadoc/doclet/testParamTaglet/pkg/C.java line 59:

> 57:      * @param t3 param 3
> 58:      */
> 59:     public static <T1, T2, T3> void genericMethod(T1 t1, T2 t2, T3 t3) {

You use `{}` to denote an empty body everywhere else in this file. Is there a reason you split it into two lines here?

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

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