JavadocParagraph

Since Checkstyle 6.0

Description

Checks the Javadoc paragraph.

Checks that:

  • There is one blank line between each of two paragraphs.
  • Each paragraph but the first has <p> immediately before the first word, with no space after.
  • First paragraph tag should not precede HTML block-tag, nested paragraph tags are allowed to do that.

ATTENTION:

This Check ignores HTML comments.

The Check ignores all the nested paragraph tags, it will not give any kind of violation if the paragraph tag is nested.

Properties

name description type default value since
allowNewlineParagraph Control whether the <p> tag should be placed immediately before the first word. boolean true 6.9
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 default check: 

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

By default, the check will report a violation if there is no empty line before or whitespace after the <p> tag: 

// violation 5 lines below '<p> tag should be preceded with an empty line'
/**
 * No tag
 *
 * <p>Tag immediately before the text
 * <p>No blank line before the tag
 *
 * <p>
 * New line after tag
 *
 * <p> Whitespace after tag
 *
 * <p><b>p tag before inline tag B, this is ok</b></p>
 */
// violation 4 lines above 'tag should be placed immediately before the first word'

public class Example1 {


  // violation 4 lines below '<p> tag should not precede HTML block-tag '<pre>''
  /**
   * No tag
   *
   * <p>
   * <pre>item 1</pre>
   *
   * <table>
   * <tbody>
   * <p>
   * <tr>
   * nested paragraph preceding block tag, this is ok.
   * </tr>
   * </tbody>
   * </table>
   */

  void foo1() {}


  // violation 2 lines below 'Redundant <p> tag'
  /**
   * <p>
   * Checks whether a redundant tag is present
   * </p>
   */

  void foo2() {}

  // violation 3 lines below 'Empty line should be followed by <p> tag'
  /**
   * Double newline.
   *
   * Some Paragraph.
   */
  void foo3() {}
}

To not allow newlines and spaces immediately after the <p> tag: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocParagraph">
      <property name="allowNewlineParagraph" value="false"/>
    </module>
  </module>
</module>

In case of allowNewlineParagraph set to false the following example will have violations: 

// violation 5 lines below '<p> tag should be preceded with an empty line'
/**
 * No tag
 *
 * <p>Tag immediately before the text
 * <p>No blank line before the tag
 *
 * <p>
 * New line after tag
 *
 * <p> Whitespace after tag
 *
 * <p><b>p tag before inline tag B, this is ok</b></p>
 */
// violation 7 lines above 'tag should be placed immediately before the first word'
// violation 5 lines above 'tag should be placed immediately before the first word'
public class Example2 {
  // 2 violations 6 lines below:
  //  'tag should be placed immediately before the first word'
  //  '<p> tag should not precede HTML block-tag '<pre>''
  /**
   * No tag
   *
   * <p>
   * <pre>item 1</pre>
   *
   * <table>
   * <tbody>
   * <p>
   * <tr>
   * nested paragraph preceding block tag, this is ok.
   * </tr>
   * </tbody>
   * </table>
   */

  void foo1() {}

  // 2 violations 4 lines below:
  //  'tag should be placed immediately before the first word'
  //  'Redundant <p> tag'
  /**
   * <p>
   * Checks whether a redundant tag is present
   * </p>
   */
  void foo2() {}

  // violation 3 lines below 'Empty line should be followed by <p> tag'
  /**
   * Double newline.
   *
   * Some Paragraph.
   */
  void foo3() {}
}

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