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

Class SingleLineJavadocCheck

  • All Implemented Interfaces:
    Configurable, Contextualizable
    public class SingleLineJavadocCheck
extends AbstractJavadocCheck

    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.

    • Property violateExecutionOnNonTightHtml - Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Type is boolean. Default value is false.
    • Property ignoredTags - Specify block tags which are ignored by the check. Type is java.lang.String[]. Default value is "".
    • Property ignoreInlineTags - Control whether inline tags must be ignored. Type is boolean. Default value is true.

    To configure the check: 

     <module name="SingleLineJavadoc"/>

    Example:

     /** @see Math */ // violation, javadoc should be multiline
 public int foo() {
   return 42;
 }

 /**
  * @return 42
  */  // ok
 public int bar() {
   return 42;
 }

 /** {@link #equals(Object)} */ // ok
 public int baz() {
   return 42;
 }

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

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

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

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

    Example:

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

 /**
  * @return 42
  */  // ok
 public int bar() {
   return 42;
 }

 /** {@link #equals(Object)} */ // ok
 public int baz() {
   return 42;
 }

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

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

    To configure the check to not ignore inline tags: 

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

    Example:

     /** @see Math */ // violation, javadoc should be multiline
 public int foo() {
   return 42;
 }

 /**
  * @return 42
  */  // ok
 public int bar() {
   return 42;
 }

 /** {@link #equals(Object)} */ // violation, javadoc should be multiline
 public int baz() {
   return 42;
 }

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

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

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

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

    Example:

     /** @see Math */ // violation, javadoc should be multiline
 public int foo() {
   return 42;
 }

 /**
  * @return 42
  */  // ok
 public int bar() {
   return 42;
 }

 /** {@link #equals(Object)} */ // ok
 public int baz() {
   return 42;
 }

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

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

    Parent is com.puppycrawl.tools.checkstyle.TreeWalker

    Violation Message Keys:

    • javadoc.missed.html.close
    • javadoc.parse.rule.error
    • javadoc.wrong.singleton.html.tag
    • singleline.javadoc
    Since:
    6.0

    • Method Detail

      • setIgnoredTags

        public void setIgnoredTags​(java.lang.String... tags)
        Setter to specify block tags which are ignored by the check.
        Parameters:
        tags - to be ignored by check.

      • setIgnoreInlineTags

        public void setIgnoreInlineTags​(boolean ignoreInlineTags)
        Setter to control whether inline tags must be ignored.
        Parameters:
        ignoreInlineTags - whether inline tags must be ignored.

      • isSingleLineJavadoc

        private static boolean isSingleLineJavadoc​(DetailAST blockCommentStart)
        Checks if comment is single line comment.
        Parameters:
        blockCommentStart - the AST tree in which a block comment starts
        Returns:
        true, if comment is single line comment.

      • hasJavadocTags

        private boolean hasJavadocTags​(DetailNode javadocRoot)
        Checks if comment has javadoc tags which are not ignored. Also works on custom tags. As block tags can be interpreted only at the beginning of a line, only the first instance is checked.
        Parameters:
        javadocRoot - javadoc root node.
        Returns:
        true, if comment has javadoc tags which are not ignored.
        See Also:
        Block and inline tags

      • hasJavadocInlineTags

        private boolean hasJavadocInlineTags​(DetailNode javadocRoot)
        Checks if comment has in-line tags which are not ignored.
        Parameters:
        javadocRoot - javadoc root node.
        Returns:
        true, if comment has in-line tags which are not ignored.
        See Also:
        JavadocTags

      • isTagIgnored

        private boolean isTagIgnored​(DetailNode javadocTagSection)
        Checks if list of ignored tags contains javadocTagSection's javadoc tag.
        Parameters:
        javadocTagSection - to check javadoc tag in.
        Returns:
        true, if ignoredTags contains javadocTagSection's javadoc tag.