Summary

Add a JavaDoc warning for @param tags that do not match the order of parameters in the documented element.

Problem

JavaDoc reports several common problems related to @param tags, such as missing, duplicate, or wrongly named tags, but it does not check whether parameters are documented in the correct order. While the order of @param tags does not affect the generated documentation, it does impact readability and maintainability of the documented source code.

Solution

Add a JavaDoc warning for @param tags if their order differs from the order of documented parameters. The warning is implemented in DocLint and can be enabled or disabled with the DocLint reference group.

Specification

When JavaDoc runs with the DocLint reference group enabled, it checks for each group of @param tags whether their order matches that of declared parameters in the documented API element. If the order differs for any two @param tags in a group, the following warning is issued:

warning: order of @param tags does not match that of declared parameters

A complete warning for a method with reversed @param tags could look as follows:

C.java:20: warning: order of @param tags does not match that of declared parameters
public void m(int i1, int i2) {
            ^

@param tags can be used for parameters of constructors and methods, type parameters, and record components. Order of @param tags is only checked within the tags of an element documenting the same kind of parameter. For example, in a generic method, order of @param tags is checked independently for type parameters and method parameters, but not between the two kinds of parameters.

For every group of @param tags, at most one warning is generated.