SingleLineJavadoc

Since Checkstyle 6.0

Description

Checks that a Javadoc block can fit in a single-line and doesn't contain block tags. Javadoc comment that contains at least one block tag should be formatted in a few lines.

Properties

name	description	type	default value	since
ignoreInlineTags	Control whether inline tags must be ignored.	boolean	`true`	6.8
ignoredTags	Specify block tags which are ignored by the check.	String[]	`{}`	6.8
violateExecutionOnNonTightHtml	Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules.	boolean	`false`	8.3

Examples

To configure the check:


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

Example:


public class Example1 {
  /** @see Math */ // violation, 'Javadoc comment should be multi-line'
  public int foo() {
    return 42;
  }

  /**
   * @return 42
   */
  public int bar() {
    return 42;
  }
  //ok below, because inline tag is ignored
  /** {@link #equals(Object)} */
  public int baz() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question
   */
  public int magic() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question</p>
   */
  public int foobar() {
    return 42;
  }
}

To configure the check with a list of ignored block tags:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SingleLineJavadoc">
      <property name="ignoredTags" value="@inheritDoc, @see"/>
    </module>
  </module>
</module>

Example:


public class Example2 {
  /** @see Math */
  public int foo() {
    return 42;
  }

  /**
   * @return 42
   */
  public int bar() {
    return 42;
  }
  //ok below, because inline tag is ignored
  /** {@link #equals(Object)} */
  public int baz() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question
   */
  public int magic() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question</p>
   */
  public int foobar() {
    return 42;
  }
}

To configure the check to not ignore inline tags:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SingleLineJavadoc">
      <property name="ignoreInlineTags" value="false"/>
    </module>
  </module>
</module>

Example:


public class Example3 {
  /** @see Math */ // violation, 'Javadoc comment should be multi-line'
  public int foo() {
    return 42;
  }

  /**
   * @return 42
   */
  public int bar() {
    return 42;
  }
  // violation below, 'Javadoc comment should be multi-line'
  /** {@link #equals(Object)} */
  public int baz() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question
   */
  public int magic() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question</p>
   */
  public int foobar() {
    return 42;
  }
}

To configure the check to report violations for Tight-HTML Rules:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SingleLineJavadoc">
      <property name="violateExecutionOnNonTightHtml" value="true"/>
    </module>
  </module>
</module>

Example:


public class Example4 {
  /** @see Math */ // violation, 'Javadoc comment should be multi-line'
  public int foo() {
    return 42;
  }

  /**
   * @return 42
   */
  public int bar() {
    return 42;
  }
  //ok below, because inline tag is ignored
  /** {@link #equals(Object)} */
  public int baz() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question
   */ // violation above, 'Unclosed HTML tag found'
  public int magic() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question</p>
   */
  public int foobar() {
    return 42;
  }
}

Example of Usage

Violation Messages

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker