Skip to content

Need default config in google_checks.xml to forbid lowercase Javadoc beginnings #17727

@VeniceWish

Description

@VeniceWish

I have read check documentation: https://checkstyle.sourceforge.io/checks/javadoc/summaryjavadoc.html
I have downloaded the latest checkstyle from: https://checkstyle.org/cmdline.html#Download_and_Run
I have executed the cli and showed it below, as cli describes the problem better than 1,000 words

From: https://google.github.io/styleguide/javaguide.html#s7.2-summary-fragment

the fragment is capitalized and punctuated as if it were a complete sentence.

Image

Code:

class Test {
  /**
   * adds an element to the list.
   *
   * @param element the element to add
   */
  public void add(String element) {}
}

Cli:

$ java -jar checkstyle-10.26.1-all.jar -c google_checks.xml Test.java 
Starting audit...
Audit done.

Formatter:

$ java -jar google-java-format-1.28.0-all-deps.jar Test.java > FormattedCode.java
$ diff -Naru Test.java FormattedCode.java
None

The Javadoc starts with “adds an element …” (lowercase a) and does not trigger any violation.
According to the style guide, this should be reported as a violation: the first word must start with a capital letter.
This is a false negative in SummaryJavadoc.

We tried configuring:

<module name="SummaryJavadoc">
  <property name="forbiddenSummaryFragments"
           value="^@return the *|^This method returns |^A [{]@code [a-zA-Z0-9]+[}]( is a ) |^\s*[^A-Z]"/>
</module>

Result:

Starting audit...
[WARN] Test.java:2: Forbidden summary fragment. [SummaryJavadoc]
Audit done.

Perhaps |^\s*[^A-Z] could be added to the google_checks.xml so that lowercase beginnings of Javadoc summaries are flagged automatically.


Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions