All Implemented Interfaces:
Configurable, Contextualizable

public class JavadocSeeTagOrderCheck extends AbstractJavadocCheck
Checks that multiple @see tags are ordered in a predictable way, roughly following the order in which their arguments are searched for by javadoc, from nearest to farthest access, from least-qualified to fully-qualified.

The order of @see tags should be:

  1. local members first
  2. simple class references after local members
  3. simple class member references after simple class references
  4. qualified class references after simple class member references
  5. qualified class member references after qualified class references
  6. package references last

Inside each member group, fields come first, then constructors, then methods. Overloaded constructors and methods with the same name must be grouped together and ordered by the number of parameters, with the fewest parameters first.

For example, this is the order recommended by the OpenJDK documentation comments style guide:

@see #field
@see #Constructor(Type, Type...)
@see #Constructor(Type id, Type id...)
@see #method(Type, Type,...)
@see #method(Type id, Type, id...)
@see Class
@see Class#field
@see Class#Constructor(Type, Type...)
@see Class#Constructor(Type id, Type id)
@see Class#method(Type, Type,...)
@see Class#method(Type id, Type id,...)
@see package.Class
@see package.Class#field
@see package.Class#Constructor(Type, Type...)
@see package.Class#Constructor(Type id, Type id)
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type id, Type, id)
@see package

References that are not in a recognizable structured form (for example @see "Effective Java", or an HTML anchor) are ignored for ordering purposes, so the check only reports violations when it is confident about the correct order. References using the Type##fragment syntax to link to a named fragment within a page (rather than to a member) are intentionally ignored as well, since such fragments are not javadoc type or member references and cannot be meaningfully compared to one.

Since:
14.2.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:
    • DOT

      private static final char DOT
      Dot.
      See Also:
    • HASH

      private static final char HASH
      Hash sign used to separate a type name from its member.
      See Also:
    • KIND_COUNT

      private static final int KIND_COUNT
      Number of JavadocSeeTagOrderCheck.Kind values, used to combine category and kind into one key.
      See Also:
    • TYPE_DEFINITION_TOKENS

      private static final BitSet TYPE_DEFINITION_TOKENS
      Token types that represent a type declaration.
    • maxReference

      The most distant structural position seen so far in the current Javadoc tree.
    • previousReference

      private JavadocSeeTagOrderCheck.SeeReference previousReference
      The reference that immediately precedes the current one.
    • lastByName

      The most recent reference for each member name within the current Javadoc tree.
    • enclosingTypeName

      private String enclosingTypeName
      Simple name of the type that most closely encloses the current Javadoc comment.
  • Constructor Details

    • JavadocSeeTagOrderCheck

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

    • 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:
    • beginJavadocTree

      public void beginJavadocTree(DetailNode rootAst)
      Description copied from class: AbstractJavadocCheck
      Called before the starting to process a tree.
      Overrides:
      beginJavadocTree in class AbstractJavadocCheck
      Parameters:
      rootAst - the root of the tree
    • findEnclosingTypeName

      private static String findEnclosingTypeName(DetailAST commentBlock)
      Finds the simple name of the type declaration that most closely encloses the given block comment, so that local @see #Name() references can be recognized as referring to a constructor of that type.
      Parameters:
      commentBlock - the block comment to start searching from
      Returns:
      the enclosing type's simple name, or an empty string if none is found
    • isTypeDefinition

      private static boolean isTypeDefinition(DetailAST ast)
      Checks whether the given node is a type declaration.
      Parameters:
      ast - the node to check
      Returns:
      true if the node is a class, interface, enum, record, or annotation declaration
    • 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
    • isStructuralViolation

      private static boolean isStructuralViolation(JavadocSeeTagOrderCheck.SeeReference current, JavadocSeeTagOrderCheck.SeeReference maximum)
      Checks whether the current reference breaks the structural order (category and field-before-constructor-before-method).
      Parameters:
      current - the current reference
      maximum - the greatest structural reference seen so far
      Returns:
      true if the structural order is violated
    • isTelescopingViolation

      private boolean isTelescopingViolation(JavadocSeeTagOrderCheck.SeeReference current)
      Checks whether the current reference breaks the telescoping order of an overloaded constructor or method with the same name.
      Parameters:
      current - the current reference
      Returns:
      true if the telescoping order is violated
    • isGroupingViolation

      private boolean isGroupingViolation(JavadocSeeTagOrderCheck.SeeReference current)
      Checks whether the current reference breaks the grouping of overloaded members with the same name.
      Parameters:
      current - the current reference
      Returns:
      true if the grouping is violated
    • lastByKey

      private static String lastByKey(JavadocSeeTagOrderCheck.SeeReference reference)
      Returns the map key that scopes a member name to its owning type and category group, so that grouping and telescoping checks only apply to overloads of the same member on the same type.
      Parameters:
      reference - the reference
      Returns:
      the map key