Package com.puppycrawl.tools.checkstyle.checks.javadoc

Class JavadocSeeTagOrderCheck

java.lang.Object
com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
com.puppycrawl.tools.checkstyle.api.AbstractCheck
com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck
com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocSeeTagOrderCheck
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