Skip to content

Allow Javadoc tag description to begin with an acronym #471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
GollapudiSrikanth wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Allow Javadoc tag description to begin with an acronym #471

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5563e06
SpringJavadocCheck now permits tag descriptions that start with conse…
GollapudiSrikanth Apr 30, 2026
809d5f0
suggested changes
GollapudiSrikanth May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion ...at-checkstyle/src/main/java/io/spring/javaformat/checkstyle/check/SpringJavadocCheck.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
* Checks that the javadoc comments follow Spring conventions.
*
* @author Phillip Webb
* @author Venkata Naga Sai Srikanth Gollapudi
*/
public class SpringJavadocCheck extends AbstractSpringCheck {

Expand Down Expand Up @@ -245,9 +246,27 @@ private void checkAnnotationFieldJavaDoc(DetailAST ast, TextBlock javadoc) {
}

private boolean startsWithUppercase(String description) {
return description.length() > 0 && Character.isUpperCase(description.charAt(0));
if(description.length() > 0 || Character.isUpperCase(description.charAt(0))) {
return false;
Copy link
Copy Markdown
Contributor

@wilkinsona wilkinsona Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The logic's now wrong as a description that starts with an upper-case character will return false. This is evident if you run the module's tests – something that you should do before submitting a PR – as SpringChecksTests now has two failures.

It also prevents startWithAcronym from being reached whenever the description starts with an upper-case character.

Copy link
Copy Markdown
Author

@GollapudiSrikanth GollapudiSrikanth May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for pointing this out — you're right. I ran the tests on my local main branch but missed running them against my PR branch after the changes.

}
return !startWithAcronym(description);
Copy link
Copy Markdown
Contributor

@wilkinsona wilkinsona Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this check belongs in a method named startsWithUppercase. I would either:

  • create a new method named something like hasCorrectCase that checks that the description either starts with an acronym or does not start with an upper-case character
  • update the code that currently calls startsWithUppercase to call both startsWithAcronym and startsWithUppercase

Copy link
Copy Markdown
Author

@GollapudiSrikanth GollapudiSrikanth May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the detailed feedback — this was really helpful.

I’ve updated the implementation to address all the points:

Refined the acronym check to ensure that only fully upper-case words (e.g. URL, HTML, JNI) are allowed, avoiding cases like STRaNGE
Fixed the logic so that acronym detection is evaluated before the uppercase check, ensuring valid cases are not incorrectly rejected and existing tests pass
Refactored the logic to improve clarity by separating concerns

I’ve also run the full test suite on this branch and confirmed everything is passing

Please let me know if you'd prefer a different structure or further refinements.

image

}

private boolean startWithAcronym(String description) {
int upperCount = 0;
for (int i = 0; i < description.length(); i++) {
char ch= description.charAt(i);
if (Character.isUpperCase(ch)) {
upperCount++;
}
else {
break;
}

}
return upperCount >= 2;
Copy link
Copy Markdown
Contributor

@wilkinsona wilkinsona Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will allow a description that starts with something like STRaNGE which is probably more than we need to allow. For now at least, we should only relax things to accept an upper-case first letter if all subsequent letters until the first space are also upper-case.

}

private void checkForNonJavadocComments(TextBlock block) {
if (block == null) {
return;
Expand Down
10 changes: 10 additions & 0 deletions spring-javaformat/spring-javaformat-checkstyle/src/test/resources/source/JavadocValid.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
*
* @param <T> this is a valid param
* @author Phillip Webb
* @author Venkata Naga Sai Srikanth Gollapudi
*/
public class JavadocValid<T> {

Expand Down Expand Up @@ -46,6 +47,15 @@ public void test2(String something) {
public String test3(String something) throws RuntimeException {
}

/**
* Do something with acronyms.
* @param something JNI hints for the thing
* @return the thing
* @throws RuntimeException on the error
*/
public String test4(String something) throws RuntimeException {
}

/**
* Class with a numeric date since.
* @since 28.12.2003
Expand Down