All Implemented Interfaces:
Configurable, Contextualizable

public class JavadocParamOrderCheck extends AbstractJavadocCheck
Checks that @param tags in Javadoc comments are in the same order as the parameters in the declaration.

Type parameters must come before regular parameters. For record declarations, record components are treated as regular parameters and must be documented after type parameters. For compact constructors, the expected parameter order is the order of the record components in the record declaration.

The check does not validate missing, extra, or duplicate @param tags. It reports only tags that move backward in the declaration order.

Since:
14.1.0
  • Field Details

    • MSG_KEY

      public static final String MSG_KEY
      A key is pointing to the warning message text in "messages.properties" file.
      See Also:
    • ELEMENT_START

      private static final String ELEMENT_START
      Html element start symbol.
      See Also:
    • ELEMENT_END

      private static final String ELEMENT_END
      Html element end symbol.
      See Also:
    • javadocTags

      private final Map<DetailNode,String> javadocTags
      Javadoc param tag names, mapped by their corresponding Javadoc node.
  • Constructor Details

    • JavadocParamOrderCheck

      public JavadocParamOrderCheck()
      Creates a new JavadocParamOrderCheck instance.
  • Method Details

    • getDefaultTokens

      public int[] getDefaultTokens()
      Description copied from class: AbstractCheck
      Returns the default token a check is interested in. Only used if the configuration for a check does not define the tokens.
      Overrides:
      getDefaultTokens in class AbstractJavadocCheck
      Returns:
      the default tokens
      See Also:
    • getRequiredTokens

      public final int[] getRequiredTokens()
      Description copied from class: AbstractCheck
      The tokens that this check must be registered for.
      Overrides:
      getRequiredTokens in class AbstractJavadocCheck
      Returns:
      the token set this must be registered for.
      See Also:
    • getDefaultJavadocTokens

      public int[] getDefaultJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      Returns the default javadoc token types a check is interested in.
      Specified by:
      getDefaultJavadocTokens in class AbstractJavadocCheck
      Returns:
      the default javadoc token types
      See Also:
    • getRequiredJavadocTokens

      public int[] getRequiredJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      The javadoc tokens that this check must be registered for.
      Overrides:
      getRequiredJavadocTokens in class AbstractJavadocCheck
      Returns:
      the javadoc token set this must be registered for.
      See Also:
    • visitToken

      public final void visitToken(DetailAST ast)
      Description copied from class: AbstractCheck
      Called to process a token.
      Overrides:
      visitToken in class AbstractJavadocCheck
      Parameters:
      ast - the token to process
    • visitJavadocToken

      public void visitJavadocToken(DetailNode ast)
      Description copied from class: AbstractJavadocCheck
      Called to process a Javadoc token.
      Specified by:
      visitJavadocToken in class AbstractJavadocCheck
      Parameters:
      ast - the token to process
    • collectParam

      private void collectParam(DetailNode ast)
      Collects a param tag.
      Parameters:
      ast - the param tag node
    • getMisorderedParamTags

      private List<Map.Entry<DetailNode,String>> getMisorderedParamTags(DetailAST ast)
      Gets collected Javadoc param tags that violate the expected declaration order.
      Parameters:
      ast - Java AST node whose Javadoc is being checked
      Returns:
      collected Javadoc param tags that violate the expected declaration order
    • getExpectedParamOrder

      private static List<String> getExpectedParamOrder(DetailAST ast)
      Gets expected param tag order for the current AST node.
      Parameters:
      ast - Java AST node whose Javadoc is being checked
      Returns:
      expected param tag order
    • addTypeParameterNames

      private static void addTypeParameterNames(Collection<String> paramNames, DetailAST ast)
      Adds type parameter names from the supplied AST node.
      Parameters:
      paramNames - destination list
      ast - node to inspect
    • addParameterNames

      private static void addParameterNames(Collection<String> paramNames, DetailAST ast)
      Adds parameter names from the supplied method or constructor AST node.
      Parameters:
      paramNames - destination list
      ast - node to inspect
    • addParameterName

      private static void addParameterName(Collection<String> paramNames, DetailAST paramDef)
      Adds a parameter name from the supplied parameter definition AST node.
      Parameters:
      paramNames - destination list
      paramDef - parameter definition node
    • addRecordComponentNames

      private static void addRecordComponentNames(Collection<String> paramNames, DetailAST recordDef)
      Adds record component names from the supplied record AST node.
      Parameters:
      paramNames - destination list
      recordDef - record definition node
    • getRecordDef

      private static DetailAST getRecordDef(DetailAST ast)
      Finds the nearest ancestor record definition node for the given AST node.
      Parameters:
      ast - the AST node to start searching from
      Returns:
      the nearest RECORD_DEF AST node
    • getRecordComponents

      private static List<DetailAST> getRecordComponents(DetailAST recordDef)
      Gets record component identifier nodes from a record definition.
      Parameters:
      recordDef - record definition node
      Returns:
      record component identifier nodes