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

[Jonathan Gibbons]

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

> 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?

That seems like a good suggestion, for a different PR.  The obvious place to implement such a warning would be in DocLint.

> > 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?
> 
> I think it is worth considering. Does it have to be a warning or would an informational notice also do? For something to be reported as warning it should have a certain gravity, I'm not sure `@param` order qualifies for it.

That's why it should be an opt-in lint-style warning. It's every bit as useful as other lint warnings, like javac's "extra semi-colon" and other minor grumbles.

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

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