Description

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.

Properties

Examples

To configure the check:

<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocSeeTagOrder"/>
  </module>
</module>

Example:

class Example1 {
  private String field;

  Example1() {}

  private void method() {}

  private void method(String value) {}

  // violation 9 lines below """@see tag '#method()' should be placed before
  //  '#method(java.lang.String)'."""
  // violation 8 lines below """@see tag '#Example1()' should be placed before
  //  '#method()'."""
  /**
   * Incorrect order: local method first, then constructor, and overloaded
   * methods not in telescoping order.
   *
   * @see #method(java.lang.String)
   * @see #method()
   * @see #Example1()
   */
  void wrongSeeTags() {}

  // ok, local member before simple class before qualified class
  /**
   * Correct order of {@code @see} tags.
   *
   * @see #field
   * @see #method()
   * @see OtherClass
   * @see java.util.List
   */
  void validSeeTags() {}
}

Example of Usage

• Checkstyle Style
• Documentation Comments Style

Violation Messages

• javadoc.parse.rule.error
• javadoc.seeTagOrder
• javadoc.unclosedHtml

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Fully Qualified Name

com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocSeeTagOrderCheck

Use this fully qualified class name in configuration when an exact class reference is required.

Parent Module

TreeWalker