GitHub Twitter Stackoverflow GoogleGroups JProfiler

JavadocUtilizingTrailingSpace

Since Checkstyle 14.4.0

On This Page

Description

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>
     */

Properties

name description type default value since
ignorePattern Specify pattern for lines that are not reported as too long. Pattern href\s*=\s*"[^"]*"|http://|https://|ftp:// 14.4.0
ignoreTooShortPattern Specify pattern for lines that are not reported as too short. Pattern [.:,]$ 14.4.0
lineLimit Specify the line length limit. int 80 14.4.0
validateOnlyJoinableLines Control whether a line is reported as too short only when the whole next line fits on it. boolean true 14.4.0
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 14.4.0

Examples

To configure the check with default settings: 


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

Example of violations:


class Example1 {
  // violation 3 lines below 'Line under-utilized (31/80). Words from below could be moved up'
  /**
   * Checks the status.
   * The company returned value
   * is invalid.
   */
  public void shortLine() { }

  // violation 2 lines below 'Line is longer than 80 characters (found 86)'
  /**
   * Refer to the specific status {@link com.wide.bundles.exceeds.limit.CompanyStatus}
   */
  public void longLine() { }

  // ok, long inline tag at start of line is allowed
  /**
   * {@link com.very.wide.bundles.name.that.exceeds.limit.CompanyStatus}
   */
  public void longTagAtStart() { }

  // ok, only a part of the next line fits
  /**
   * The status is read from the registry of companies
   * that is configured for the country of the given company.
   */
  public void partOfNextLine() { }

  // violation 2 lines below 'Line is longer than 80 characters (found 85)'
  /**
   * @return the status of the company, which is defined by the registry of companies
   */
  public String blockTagTooLong() { return ""; }

  // ok, the content of a pre element is ignored
  /**
   * Example:
   * <pre>
   * CompanyStatus status = new CompanyStatusFactory().createStatus(companyNumber);
   * </pre>
   */
  public void preElementContent() { }

  // ok, a line that has a URL is not reported as too long
  /** See https://example.com/documentation/company-registry/api/v2/status-endpoints/details */
  public void longUrl() { }
}

To configure the check with a custom line limit: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocUtilizingTrailingSpace">
      <property name="lineLimit" value="100"/>
    </module>
  </module>
</module>

Example2:


class Example2 {
  // violation 3 lines below 'Line under-utilized (31/100). Words from below could be moved up'
  /**
   * Checks the status.
   * The company returned value
   * is invalid.
   */
  public void shortLine() { }

  // ok, line is under 100 characters
  /**
   * Refer to the specific status {@link com.wide.bundles.exceeds.limit.CompanyStatus}
   */
  public void longLine() { }

  // ok, long inline tag at start of line is allowed
  /**
   * {@link com.very.wide.bundles.name.that.exceeds.limit.CompanyStatus}
   */
  public void longTagAtStart() { }

  // ok, only a part of the next line fits
  /**
   * The status is read from the registry of companies
   * that is configured for the country of the given company.
   */
  public void partOfNextLine() { }

  // ok, line is under 100 characters
  /**
   * @return the status of the company, which is defined by the registry of companies
   */
  public String blockTagTooLong() { return ""; }

  // ok, the content of a pre element is ignored
  /**
   * Example:
   * <pre>
   * CompanyStatus status = new CompanyStatusFactory().createStatus(companyNumber);
   * </pre>
   */
  public void preElementContent() { }

  // ok, line is under 100 characters
  /** See https://example.com/documentation/company-registry/api/v2/status-endpoints/details */
  public void longUrl() { }
}

To configure the check to report long lines that have a URL or a link: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocUtilizingTrailingSpace">
      <property name="ignorePattern" value="^$"/>
    </module>
  </module>
</module>

Example3:


class Example3 {
  // violation 3 lines below 'Line under-utilized (31/80). Words from below could be moved up'
  /**
   * Checks the status.
   * The company returned value
   * is invalid.
   */
  public void shortLine() { }

  // violation 2 lines below 'Line is longer than 80 characters (found 86)'
  /**
   * Refer to the specific status {@link com.wide.bundles.exceeds.limit.CompanyStatus}
   */
  public void longLine() { }

  // ok, long inline tag at start of line is allowed
  /**
   * {@link com.very.wide.bundles.name.that.exceeds.limit.CompanyStatus}
   */
  public void longTagAtStart() { }

  // ok, only a part of the next line fits
  /**
   * The status is read from the registry of companies
   * that is configured for the country of the given company.
   */
  public void partOfNextLine() { }

  // violation 2 lines below 'Line is longer than 80 characters (found 85)'
  /**
   * @return the status of the company, which is defined by the registry of companies
   */
  public String blockTagTooLong() { return ""; }

  // ok, the content of a pre element is ignored
  /**
   * Example:
   * <pre>
   * CompanyStatus status = new CompanyStatusFactory().createStatus(companyNumber);
   * </pre>
   */
  public void preElementContent() { }

  // violation below 'Line is longer than 80 characters (found 93)'
  /** See https://example.com/documentation/company-registry/api/v2/status-endpoints/details */
  public void longUrl() { }
}

To configure the check to report lines that stop early after punctuation: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocUtilizingTrailingSpace">
      <property name="ignoreTooShortPattern" value="^$"/>
    </module>
  </module>
</module>

Example4:


class Example4 {
  // violation 2 lines below 'Line under-utilized (23/80). Words from below could be moved up'
  /**
   * Checks the status.
   * The company returned value
   * is invalid.
   */
  public void shortLine() { }

  // violation 2 lines below 'Line is longer than 80 characters (found 86)'
  /**
   * Refer to the specific status {@link com.wide.bundles.exceeds.limit.CompanyStatus}
   */
  public void longLine() { }

  // ok, long inline tag at start of line is allowed
  /**
   * {@link com.very.wide.bundles.name.that.exceeds.limit.CompanyStatus}
   */
  public void longTagAtStart() { }

  // ok, only a part of the next line fits
  /**
   * The status is read from the registry of companies
   * that is configured for the country of the given company.
   */
  public void partOfNextLine() { }

  // violation 2 lines below 'Line is longer than 80 characters (found 85)'
  /**
   * @return the status of the company, which is defined by the registry of companies
   */
  public String blockTagTooLong() { return ""; }

  // ok, the content of a pre element is ignored
  /**
   * Example:
   * <pre>
   * CompanyStatus status = new CompanyStatusFactory().createStatus(companyNumber);
   * </pre>
   */
  public void preElementContent() { }

  // ok, a line that has a URL is not reported as too long
  /** See https://example.com/documentation/company-registry/api/v2/status-endpoints/details */
  public void longUrl() { }
}

To configure the check to report lines that can take a part of the next line: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocUtilizingTrailingSpace">
      <property name="validateOnlyJoinableLines" value="false"/>
    </module>
  </module>
</module>

Example5:


class Example5 {
  // violation 3 lines below 'Line under-utilized (31/80). Words from below could be moved up'
  /**
   * Checks the status.
   * The company returned value
   * is invalid.
   */
  public void shortLine() { }

  // violation 2 lines below 'Line is longer than 80 characters (found 86)'
  /**
   * Refer to the specific status {@link com.wide.bundles.exceeds.limit.CompanyStatus}
   */
  public void longLine() { }

  // ok, long inline tag at start of line is allowed
  /**
   * {@link com.very.wide.bundles.name.that.exceeds.limit.CompanyStatus}
   */
  public void longTagAtStart() { }

  // violation 2 lines below 'Line under-utilized (54/80). Words from below could be moved up'
  /**
   * The status is read from the registry of companies
   * that is configured for the country of the given company.
   */
  public void partOfNextLine() { }

  // violation 2 lines below 'Line is longer than 80 characters (found 85)'
  /**
   * @return the status of the company, which is defined by the registry of companies
   */
  public String blockTagTooLong() { return ""; }

  // ok, the content of a pre element is ignored
  /**
   * Example:
   * <pre>
   * CompanyStatus status = new CompanyStatusFactory().createStatus(companyNumber);
   * </pre>
   */
  public void preElementContent() { }

  // ok, a line that has a URL is not reported as too long
  /** See https://example.com/documentation/company-registry/api/v2/status-endpoints/details */
  public void longUrl() { }
}

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.

Fully Qualified Name

com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocUtilizingTrailingSpaceCheck

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

Parent Module

TreeWalker