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

Class JavadocUtilizingTrailingSpaceCheck

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.JavadocUtilizingTrailingSpaceCheck
All Implemented Interfaces:
Configurable, Contextualizable
public class JavadocUtilizingTrailingSpaceCheck extends AbstractJavadocCheck
Checks that Javadoc lines efficiently utilize the available horizontal space.

Every line of a Javadoc comment is compared with lineLimit, the preferred line length. A line is reported when it is longer than the limit, or when it stops early although the next line would still have fit on it. Blank lines are never reported. The examples on this page use the default limit of 80 characters, and show the Javadoc of a method, indented by four spaces.

Lines that stop too early. A line is reported when the whole next line would still fit on it. The fix is to join the two lines, so the comment gets one line shorter. When only a part of the next line would fit, the line is not reported, because moving words up would not make the comment shorter. Lines are never joined with a line that is blank, or that starts with a block tag, an inline tag, a URL or an HTML tag, so the line before such a line is not reported. 


     // violation, the second line would fit on the first line
     /**
      * Not part of the API. This is returned when a type
      * is not known.
      */

     // ok, only a part of the second line would fit on the first line
     /**
      * Not part of the API. This is returned when a type
      * not known to this wrapper is returned.
      */

Lines that could take more words. When validateOnlyJoinableLines is set to false, words are expected to fill a line up to the limit, so a line is also reported when only the first word of the next line would still fit on it. The fix is to move words up until the next word does not fit. 


     // violation, "not" would fit on the first line
     /**
      * Not part of the API. This is returned when a type
      * not known to this wrapper is returned.
      */

     // ok
     /**
      * Not part of the API. This is returned when a type not known to this
      * wrapper is returned.
      */

Lines that end with punctuation. A line that matches ignoreTooShortPattern is not reported as stopping too early, and no words are moved up to it. By default this is every line that ends with a period, a colon or a comma, so a sentence, or a part of it, can end before the limit. Trailing whitespace of the line is ignored when the pattern is applied. The line after such a line is checked on its own. Such lines can still be reported as too long. 


     // ok, the first line ends with a period
     /**
      * Not part of the API.
      * This is returned when a type not known to this wrapper is returned.
      */

     // violation, the third line would fit on the second line
     /**
      * Not part of the API.
      * This is returned when a type not
      * known to this wrapper is returned.
      */

Lines that are too long. A line is reported when it is longer than the limit. The fix is to wrap it at a word. 


     // violation, longer than 80 characters
     /**
      * Creates a client for the service and loads its settings from the given file path.
      */

     // ok
     /**
      * Creates a client for the service and loads its settings from the given
      * file path.
      */

Block tags. The value of a block tag, such as @param, @return or @throws, is checked like any other text. A line that has only the name of the block tag is not reported, so the value can start on the next line. A line that starts with a block tag is never joined to the line before it. 


     // violation, longer than 80 characters
     /**
      * @return Date the company was closed or dissolved, see {@link #getStatus()}.
      */

     // ok, the value starts on the next line
     /**
      * @return
      *     Date the company was closed or dissolved, see {@link #getStatus()}.
      */

     // ok, wrapped before the inline tag
     /**
      * @return Date the company was closed or dissolved, see
      * {@link #getStatus()}.
      */

Inline tags. An inline tag, such as a link to a class, cannot be wrapped. A line that starts with an inline tag and has nothing else on it is not reported, even when it is longer than the limit. When other words follow on the same line, the line is reported, because those words can move to the next line. A block tag never gets this exception for its value. 


     // ok, a tag alone on a line may be longer than 80 characters
     /**
      * Refer to the method
      * {@link com.example.registry.status.CompanyStatusRegistry#findStatus(String)}
      */

     // violation, other words follow the tag
     /**
      * {@link com.example.registry.status.CompanyStatusRegistry#findStatus(String)} finds it.
      */

URLs and links. A URL cannot be wrapped, so a line that matches ignorePattern is not reported as too long. By default this is every line that has a URL or the href attribute of a link. A block tag line whose value starts with a link, such as @see <a href="...">, is therefore not reported, whether the link ends on that line or on a later one. Such lines can still be reported as stopping too early. 


     // ok, lines that have a URL or a link may be longer than 80 characters
     /**
      * See https://example.com/documentation/company-registry/api/v2/status-endpoints/details
      *
      * @see <a href="https://example.com/documentation/company-registry/api/v2/status">
      *     Status endpoints</a>
      */

HTML. A line that starts with an HTML tag, such as <p> or </li>, is not reported as too short, and it is not joined to the line before it, so tags can be placed on their own lines. Such a line, and the text inside an HTML element, must still not be longer than the limit. 


     // ok, a line that starts with an HTML tag is never too short
     /**
      * <p>Companies House allows you to query
      * information on registered companies in Britain.</p>
      */

     // violation, text inside an HTML element is checked
     /**
      * <ul>
      * <li>Static configuration reads files from the classpath or a given path.</li>
      * </ul>
      */

     // ok
     /**
      * <ul>
      * <li>Static configuration reads files from the classpath or a given
      * path.</li>
      * </ul>
      */

Pre and code elements. The content of <pre> and <code> elements, and HTML comments, is ignored, so code samples can keep their own formatting. 


     // ok, the content of a pre element is ignored
     /**
      * Example:
      * <pre>
      * new CompanyRegistry().findStatus("00000006").orElseThrow(NotRegisteredException::new);
      * </pre>
      */
Since:
14.4.0

  • Field Details

  • Constructor Details

  • Method Details

    • getDefaultJavadocTokens

      public int[] getDefaultJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      Returns the default javadoc token types a check is interested in.
      Specified by:
      getDefaultJavadocTokens in class AbstractJavadocCheck
      Returns:
      the default javadoc token types
      See Also:

    • getRequiredJavadocTokens

      public int[] getRequiredJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      The javadoc tokens that this check must be registered for.
      Overrides:
      getRequiredJavadocTokens in class AbstractJavadocCheck
      Returns:
      the javadoc token set this must be registered for.
      See Also:

    • setLineLimit

      public void setLineLimit(int limit)
      Setter to specify the line length limit.
      Parameters:
      limit - the maximum length to target for Javadoc lines
      Since:
      14.4.0

    • setIgnorePattern

      public void setIgnorePattern(Pattern pattern)
      Setter to specify pattern for lines that are not reported as too long.
      Parameters:
      pattern - a pattern.
      Since:
      14.4.0

    • setIgnoreTooShortPattern

      public void setIgnoreTooShortPattern(Pattern pattern)
      Setter to specify pattern for lines that are not reported as too short.
      Parameters:
      pattern - a pattern.
      Since:
      14.4.0

    • setValidateOnlyJoinableLines

      public void setValidateOnlyJoinableLines(boolean validateOnlyJoinableLines)
      Setter to control whether a line is reported as too short only when the whole next line fits on it.
      Parameters:
      validateOnlyJoinableLines - true if a line is reported as too short only when the whole next line fits on it, false if the first word of the next line is enough.
      Since:
      14.4.0

    • beginJavadocTree

      public void beginJavadocTree(DetailNode rootAst)
      Description copied from class: AbstractJavadocCheck
      Called before the starting to process a tree.
      Overrides:
      beginJavadocTree in class AbstractJavadocCheck
      Parameters:
      rootAst - the root of the tree

    • finishJavadocTree

      public void finishJavadocTree(DetailNode rootAst)
      Description copied from class: AbstractJavadocCheck
      Called after finished processing a tree.
      Overrides:
      finishJavadocTree in class AbstractJavadocCheck
      Parameters:
      rootAst - the root of the tree

    • visitJavadocToken

      public void visitJavadocToken(DetailNode ast)
      Description copied from class: AbstractJavadocCheck
      Called to process a Javadoc token.
      Specified by:
      visitJavadocToken in class AbstractJavadocCheck
      Parameters:
      ast - the token to process

    • leaveJavadocToken

      public void leaveJavadocToken(DetailNode ast)
      Description copied from class: AbstractJavadocCheck
      Called after all the child nodes have been process.
      Overrides:
      leaveJavadocToken in class AbstractJavadocCheck
      Parameters:
      ast - the token leaving

    • validateLines

      private void validateLines()
      Validates all collected lines for violations.

    • isTooShort

      private boolean isTooShort(int index)
      Decides whether the line at the given index is too short (i.e. we should have pulled content from the next line).
      Parameters:
      index - the line index to check
      Returns:
      true if the line is too short

    • handleNewline

      private void handleNewline(DetailNode node)
      Handles a newline token.
      Parameters:
      node - the newline node

    • handleBlockTag

      private void handleBlockTag(DetailNode node)
      Handles a Javadoc block tag node. A line that starts a block tag cannot be merged into the previous line, but its value is still validated.
      Parameters:
      node - the block tag node

    • handleText

      private void handleText(DetailNode node)
      Handles a TEXT node.
      Parameters:
      node - the text node

    • handleInlineTag

      private void handleInlineTag(DetailNode node)
      Handles a Javadoc inline tag node. The tag is measured as a whole and its content is skipped.
      Parameters:
      node - the inline tag node

    • handleHtmlElement

      private void handleHtmlElement(DetailNode element)
      Handles an HTML element. The content of pre and code elements is skipped.
      Parameters:
      element - the HTML element node

    • handleHtmlTag

      private void handleHtmlTag(DetailNode node)
      Handles an HTML start tag, end tag or void element. A line that starts with such a tag is never reported as too short, but it can still be too long.
      Parameters:
      node - the HTML tag node

    • skipNode

      private void skipNode(DetailNode node)
      Skips the subtree of the given node. If the node spans several lines, the line where it starts is marked, because the lines after it are not adjacent to the lines that were skipped.
      Parameters:
      node - the node to skip

    • updateLengthToEnd

      private void updateLengthToEnd(DetailNode node)
      Extends the current line to the end of the given node, if the node ends on the line where it starts.
      Parameters:
      node - the node to measure

    • lastLeaf

      private static DetailNode lastLeaf(DetailNode node)
      Finds the last leaf of the subtree of the given node.
      Parameters:
      node - the root of the subtree
      Returns:
      the last leaf, which is the node itself if it has no children

    • canPullFromNextLine

      private boolean canPullFromNextLine(int currentIndex)
      Checks if content can be pulled from the next line.
      Parameters:
      currentIndex - current line index
      Returns:
      true if the content to pull from the next content line fits within lineLimit

    • getPullLength

      private int getPullLength(JavadocUtilizingTrailingSpaceCheck.JavadocLine nextLine)
      Returns the length of the content that has to fit on the line before the given line, for that line to be too short.
      Parameters:
      nextLine - the line to pull content from
      Returns:
      the length of the whole content of the line if only joinable lines are validated, the length of its first word otherwise

    • initCurrentLine

      private void initCurrentLine(int lineNumber)
      Initializes the current line if needed.
      Parameters:
      lineNumber - the source line number

    • commitCurrentLine

      private void commitCurrentLine()
      Commits the current line to the lines list and clears it.