JavadocStyle doesn't work with inline @return

[Juuxel]

I have read check documentation: https://checkstyle.org/config_javadoc.html#JavadocStyle
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

C:\Users\Juuz>javac Test.java

C:\Users\Juuz>type checkstyle.xml
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
          "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
          "https://checkstyle.org/dtds/configuration_1_3.dtd">

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

C:\Users\Juuz>type Test.java
class Test {
    /**
     * {@return a string}
     */
    String foo() {
        return "Hello, world";
    }
}

C:\Users\Juuz>set RUN_LOCALE="-Duser.language=en -Duser.country=US"

C:\Users\Juuz>java %RUN_LOCALE% -jar Downloads\checkstyle-10.6.0-all.jar -c checkstyle.xml Test.java
Starting audit...
[ERROR] C:\Users\Juuz\Test.java:2: First sentence should end with a period. [JavadocStyle]
Audit done.
Checkstyle ends with 1 errors.

---

JavadocStyle requires a period after the first sentence, but it doesn't consider inline {@return} tags which insert a period after the contents.

For the example file with {@return a string}, this is what javadoc -package Test.java (JDK 19) generates:

This seems to be related to #10776, which is a similar issue with a different check.

Note: A workaround is to add a . after the {@return} tag.

[romani]

attention

checkstyle/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheck.java

Lines 300 to 301 in 887aab9

	public class JavadocStyleCheck
	extends AbstractCheck {

this module is old and does not use grammar and AST to deal with, I hope fix can be applied to Check, but it might be more challenging as parsing is done by regexp or other custom techniques.

[romani]

We might be on to to extend this Check to support this for a bit.
But conceptually we need to remove from this Check such validation completely.

We already have validation for summary at https://checkstyle.org/config_javadoc.html#SummaryJavadoc there a lot of nuances of this validation, so better to not have super check that does all validations on javadoc.

[rnveach]

The check shouldn't be removed, but the common functionality between it and other checks should be removed like we have done in other areas.

JavadocStyle has scope and java token support while SummaryJavadoc does not. It is not clear how checkHtml compares to violateExecutionOnNonTightHtml.

[Bananeweizen]

I'm not sure if the refactoring of the Javadoc checks already covers this: Besides the mentioned checks, also the JavadocMethod check has the same issue.

[romani]

Fix is merged