On Tue, 22 Oct 2024 15:05:05 GMT, Jaikiran Pai <j...@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
