RFR: 8342827: Fix order of @param tags in other modules

[Hannes Wallnöfer]

On Tue, 22 Oct 2024 15:05:05 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> Please review a doc-only change to fix the order of javadoc @param tags in in various OpenJDK modules. This is the third and last PR to fix the order of @param tags in OpenJDK libraries.
>> 
>> We are working on a javadoc feature to add an opt-in doclint warning for @param tags that don't match the order of parameters in the documented element. The warning will be enabled in OpenJDK builds and covers all uses of the @param tag, i.e. parameters of executable elements, type parameters, and record components.
>> 
>> I compared the generated API docs built with this branch with API docs built from master branch to make sure they are identical.
>
> Hello Hannes, since `@param` requires a parameter name and since javadoc already warns about incorrect `@param` names (that don't match the name of the method parameter), does the order in which the `@param` is listed in the javadoc text matter? I looked at https://bugs.openjdk.org/browse/JDK-8279931 but that doesn't tell why the order would be important.

@jaikiran it does not matter for the generated documentation because we already [put the tags in the correct order][JDK-8234682]. So it's purely a code hygiene issue to make doc comments easier to read and maintain. 

[JDK-8234682]: https://bugs.openjdk.org/browse/JDK-8234682

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

PR Comment: https://git.openjdk.org/jdk/pull/21637#issuecomment-2429770979