Repository: checkstyle/checkstyle

Problem statement:
JavadocMethod: new property 'allowInlineReturn' to support for Javadoc return tag as inline
I have downloaded the latest cli 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

**How it works Now:**

```bash
$ javac Foo.java
$ javadoc Foo.java 
Loading source file Foo.java...
Constructing Javadoc information...
Building index for all the packages and classes...
Standard Doclet version 16+36
Building tree for all the packages and classes...
Generating ./Foo.html...
Generating ./package-summary.html...
Generating ./package-tree.html...
Generating ./overview-tree.html...
Building index for all classes...
Generating ./allclasses-index.html...
Generating ./allpackages-index.html...
Generating ./index-all.html...
Generating ./index.html...
Generating ./help-doc.html...
```

config.xml
```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">
   <property name="fileExtensions" value="java"/>
   <module name="TreeWalker">
       <module name="JavadocMethod">
            <property name="accessModifiers" value="public"/>
       </module>
   </module>
</module>
```

Foo.java
```java
/**
 * Test
 */
public class Foo {

    /**
     * {@return the foo}
     */
    public int getFoo() { return 0; } // violation

    /**
     * Returns the bar
     * @return the bar
     */
    public int getBar() { return 0; }

}
```

```bash
$ RUN_LOCALE="-Duser.language=en -Duser.country=US"
$ java $RUN_LOCALE -jar ~/Downloads/checkstyle-9.0-all.jar -c config.xml Foo.java
Starting audit...
[ERROR] /tmp/Foo.java:9: @return tag should be present and have description. [JavadocMethod]
Audit done.
Checkstyle ends with 1 errors.
```

**Is your feature request related to a problem? Please describe.**
Add support for Javadoc inline return tag

**Describe the solution you'd like**
Both methods to be treated the same (getFoo and getBar), as it is by the Javadoc

**Additional context**
The support for this syntax was added in JDK 16
https://bugs.openjdk.java.net/browse/JDK-8075778

```
rivanov@p5510:/var/tmp$ javadoc Foo.java
Loading source file Foo.java...
Constructing Javadoc information...
Standard Doclet version 11
Building tree for all the packages and classes...
Generating ./Foo.html...
Foo.java:7: error: no tag name after @
     * {@return the foo}
       ^
Foo.java:9: warning: no @return
    public int getFoo() { return 0; } // violation
               ^


/var/tmp$ export JAVA_HOME=/opt/jvm/jdk-17.0.1/
/var/tmp$ export PATH=$JAVA_HOME/bin:$PATH
rivanov@p5510:/var/tmp$ javadoc Foo.java
Loading source file Foo.java...
Constructing Javadoc information...
Building index for all the packages and classes...
Standard Doclet version 17.0.1+12-39
Building tree for all the packages and classes...
Generating ./Foo.html...

```
![image](https://user-images.githubusercontent.com/812984/147023606-4df25f74-666d-4c53-933d-fcba6a9d7ff5.png)



Hints:
Similar to #10014
The pattern should be updated to something like 
```java
    /** Compiled regexp to match Javadoc tags with no argument. */
    private static final Pattern MATCH_JAVADOC_NOARG =
            CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*(\{?@return|@see)\\s+\\S");
```
 
I would like to get started on this project, can you please suggest to me any beginner-friendly issues that I could start fixing.
Can we have an example of what the Javadoc tool prints as its summary in the HTML pages using this example to show what it does in this situation?

> The support for this syntax was added in JDK 16

So how does pre-JDK 16 handle this compared to JDK 16+?
@rnveach 
pre-JDK 16:
![image](https://user-images.githubusercontent.com/13357965/132101452-16c46faf-14e1-4d00-8c3d-ad0fea91dd31.png)
16+:
![image](https://user-images.githubusercontent.com/13357965/132101463-fff60673-c731-47b8-abe8-cd25516b62eb.png)

@Thihup , please update PR description with output of latest cli 9.0.
In 8.42, https://checkstyle.org/releasenotes.html#Release_8.42 we did big breaking compatibility update for this Check.
@romani Updated! I guess the main change is from `scope` to `accessModifiers`. 
In short from the pictures,
Pre-JDK 16 sees the text as only the summary and has nothing for the return.
JDK 16+ sees the text as the summary and the return.

@romani What is your opinion on this? Should we add a property that just allows `{@return XXX}` to act as both summary and return?

It's main purpose would be just to decide if a violation or no-violation should be placed if `{@return XXX}` exists and nothing else.  It could be named `allowInlineReturn` and be default to `false` to not be a sort-of breaking change.
Extra note while I am going through the OpenJDK item, it looks like this inline return must be the first item in the javadoc to be valid.
https://github.com/openjdk/jdk/commit/b29f9cd7#diff-c38f0230e3d3894de14e518961fd61dcf270ca6e10fb487cc68f6d2b3b505991R60
https://github.com/openjdk/jdk/commit/b29f9cd7#diff-873b8bd2b8ecd4acd77f5e500aa0ef469787e2e8976dd8bfc530c19465fcd9d0R257

More examples at:
https://github.com/openjdk/jdk/commit/b29f9cd7#diff-873b8bd2b8ecd4acd77f5e500aa0ef469787e2e8976dd8bfc530c19465fcd9d0
I need to see whole html page, summary sentence is something that is printed in table of all methods.
@romani Here is the requested information.
http://rveach.no-ip.org/checkstyle/regression/9745/
http://rveach.no-ip.org/checkstyle/regression/9745/11/
http://rveach.no-ip.org/checkstyle/regression/9745/16/

````
$ /usr/lib/jvm/java-16-openjdk/bin/javadoc -d 16 ./Foo.java
Loading source file ./Foo.java...
Constructing Javadoc information...
Creating destination directory: "16/"
Building index for all the packages and classes...
Standard Doclet version 16.0.2+7-67
Building tree for all the packages and classes...
Generating 16/Foo.html...
Generating 16/package-summary.html...
Generating 16/package-tree.html...
Generating 16/overview-tree.html...
Building index for all classes...
Generating 16/allclasses-index.html...
Generating 16/allpackages-index.html...
Generating 16/index-all.html...
Generating 16/index.html...
Generating 16/help-doc.html...

$ javadoc -d 11 ./Foo.java
Loading source file ./Foo.java...
Constructing Javadoc information...
Creating destination directory: "11/"
Standard Doclet version 11.0.11
Building tree for all the packages and classes...
Generating 11/Foo.html...
./Foo.java:7: warning - invalid usage of tag {@return the foo}
./Foo.java:7: warning - invalid usage of tag {@return the foo}
Generating 11/package-summary.html...
Generating 11/package-tree.html...
Generating 11/constant-values.html...
Building index for all the packages and classes...
Generating 11/overview-tree.html...
Generating 11/index-all.html...
./Foo.java:7: warning - invalid usage of tag {@return the foo}
Building index for all classes...
Generating 11/allclasses-index.html...
Generating 11/allpackages-index.html...
Generating 11/deprecated-list.html...
Building index for all classes...
Generating 11/allclasses.html...
Generating 11/allclasses.html...
Generating 11/index.html...
Generating 11/help-doc.html...
3 warnings
````
Any update on this?
@Frettman , please do not hesitate to send PR. Whole code is at https://github.com/checkstyle/checkstyle/blob/master/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheck.java
Testing fully automated, how to run debug https://checkstyle.org/idea.html
I mistakenly thought I could use inline `@return` tag because of #10776, but I am actually hitting the current issue :D
Anyway, I wanted to report here that this is indeed blocking uses of this javadoc feature.

I know Checkstyle development is based on the work of volunteers. Unfortunately I don't have the bandwidth to work on this right now. If my bandwidth clears I will try to fix this. Don't count on me if you don't see a PR from me.

Patch:
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheck.java
--- a/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheck.java
+++ b/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheck.java
@@ -115,6 +115,11 @@
  * Default value is {@code public, protected, package, private}.
  * </li>
  * <li>
+ * Property {@code allowInlineReturn} - Control whether to allow inline return tags.
+ * Type is {@code boolean}.
+ * Default value is {@code false}.
+ * </li>
+ * <li>
  * Property {@code allowMissingParamTags} - Control whether to ignore violations
  * when a method has parameters but does not have matching {@code param} tags in the javadoc.
  * Type is {@code boolean}.
@@ -256,6 +261,9 @@ public class JavadocMethodCheck extends AbstractCheck {
     /** Compiled regexp to match Javadoc tags with no argument. */
     private static final Pattern MATCH_JAVADOC_NOARG =
             CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*@(return|see)\\s+\\S");
+    /** Compiled regexp to match Javadoc tags with no argument allowing inline return tag. */
+    private static final Pattern MATCH_JAVADOC_NOARG_INLINE_RETURN =
+            CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*\\{?@(return|see)\\s+\\S");
     /** Compiled regexp to match first part of multilineJavadoc tags. */
     private static final Pattern MATCH_JAVADOC_NOARG_MULTILINE_START =
             CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*@(return|see)\\s*$");
@@ -263,6 +271,11 @@ public class JavadocMethodCheck extends AbstractCheck {
     private static final Pattern MATCH_JAVADOC_NOARG_CURLY =
             CommonUtil.createPattern("\\{\\s*@(inheritDoc)\\s*\\}");
 
+    /**
+     * Control whether to allow inline return tags.
+     */
+    private boolean allowInlineReturn;
+
     /** Specify the access modifiers where Javadoc comments are checked. */
     private AccessModifierOption[] accessModifiers = {
         AccessModifierOption.PUBLIC,
@@ -291,6 +304,16 @@ public class JavadocMethodCheck extends AbstractCheck {
     /** Specify annotations that allow missed documentation. */
     private Set<String> allowedAnnotations = Set.of("Override");
 
+    /**
+     * Setter to control whether to allow inline return tags.
+     *
+     * @param value a {@code boolean} value
+     * @since 10.22.1
+     */
+    public void setAllowInlineReturn(boolean value) {
+        allowInlineReturn = value;
+    }
+
     /**
      * Setter to control whether to validate {@code throws} tags.
      *
@@ -511,7 +534,11 @@ private boolean hasShortCircuitTag(final DetailAST ast, final List<JavadocTag> t
      * @param comment the Javadoc comment
      * @return the tags found
      */
-    private static List<JavadocTag> getMethodTags(TextBlock comment) {
+    private List<JavadocTag> getMethodTags(TextBlock comment) {
+        Pattern matchJavadocNoArg = MATCH_JAVADOC_NOARG;
+        if (allowInlineReturn) {
+            matchJavadocNoArg = MATCH_JAVADOC_NOARG_INLINE_RETURN;
+        }
         final String[] lines = comment.getText();
         final List<JavadocTag> tags = new ArrayList<>();
         int currentLine = comment.getStartLineNo() - 1;
@@ -524,7 +551,7 @@ private static List<JavadocTag> getMethodTags(TextBlock comment) {
             final Matcher javadocArgMissingDescriptionMatcher =
                 MATCH_JAVADOC_ARG_MISSING_DESCRIPTION.matcher(lines[i]);
             final Matcher javadocNoargMatcher =
-                MATCH_JAVADOC_NOARG.matcher(lines[i]);
+                matchJavadocNoArg.matcher(lines[i]);
             final Matcher noargCurlyMatcher =
                 MATCH_JAVADOC_NOARG_CURLY.matcher(lines[i]);
             final Matcher noargMultilineStart =
diff --git a/src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/Example8.java b/src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/Example8.java
new file mode 100644
--- /dev/null
+++ b/src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/Example8.java
@@ -0,0 +1,27 @@
+/*xml
+<module name="Checker">
+  <module name="TreeWalker">
+    <module name="JavadocMethod">
+        <property name="allowInlineReturn" value="true"/>
+    </module>
+  </module>
+</module>
+*/
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+// xdoc section -- start
+public class Example8 {
+
+  /**
+   * {@return the foo}
+   */
+  public int getFoo() { return 0; }
+
+  /**
+   * Returns the bar
+   * @return the bar
+   */
+  public int getBar() { return 0; }
+
+}
+// xdoc section -- end


Test patch:
diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheckTest.java
--- a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheckTest.java
+++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheckTest.java
@@ -590,4 +590,25 @@ public void testJavadocMethodAboveComments() throws Exception {
         verifyWithInlineConfigParser(
                 getPath("InputJavadocMethodAboveComments.java"), expected);
     }
+
+    @Test
+    public void testJavadocMethodAllowInlineReturn() throws Exception {
+        final String[] expected = {
+            "32: " + getCheckMessage(MSG_RETURN_EXPECTED),
+            "39: " + getCheckMessage(MSG_RETURN_EXPECTED),
+        };
+        verifyWithInlineConfigParser(
+                getPath("InputJavadocMethodAllowInlineReturn.java"), expected);
+    }
+
+    @Test
+    public void testJavadocMethodDoNotAllowInlineReturn() throws Exception {
+        final String[] expected = {
+            "21: " + getCheckMessage(MSG_RETURN_EXPECTED),
+            "33: " + getCheckMessage(MSG_RETURN_EXPECTED),
+            "40: " + getCheckMessage(MSG_RETURN_EXPECTED),
+        };
+        verifyWithInlineConfigParser(
+                getPath("InputJavadocMethodDoNotAllowInlineReturn.java"), expected);
+    }
 }
diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAllowInlineReturn.java b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAllowInlineReturn.java
new file mode 100644
--- /dev/null
+++ b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAllowInlineReturn.java
@@ -0,0 +1,41 @@
+/*
+JavadocMethod
+allowInlineReturn = true
+allowedAnnotations = (default)Override
+validateThrows = (default)false
+accessModifiers = (default)public, protected, package, private
+allowMissingParamTags = (default)false
+allowMissingReturnTag = (default)false
+tokens = (default)METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAllowInlineReturn {
+
+    /**
+     * {@return the foo}
+     */
+    public int getFoo() { return 0; }
+
+    /**
+     * Returns the bar
+     * @return the bar
+     */
+    public int getBar() { return 0; }
+
+    /**
+     * Returns the fiz
+     */
+    public int getFiz() { return 0; }
+    // violation above, '@return tag should be present and have description.'
+
+    /**
+     * Returns the baz
+     * @see "getFoo"
+     */
+    public int getBaz() { return 0; }
+    // violation above, '@return tag should be present and have description.'
+}
diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodDoNotAllowInlineReturn.java b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodDoNotAllowInlineReturn.java
new file mode 100644
--- /dev/null
+++ b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodDoNotAllowInlineReturn.java
@@ -0,0 +1,42 @@
+/*
+JavadocMethod
+allowInlineReturn = (default)false
+allowedAnnotations = (default)Override
+validateThrows = (default)false
+accessModifiers = (default)public, protected, package, private
+allowMissingParamTags = (default)false
+allowMissingReturnTag = (default)false
+tokens = (default)METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodDoNotAllowInlineReturn {
+
+    /**
+     * {@return the foo}
+     */
+    public int getFoo() { return 0; }
+    // violation above, '@return tag should be present and have description.'
+
+    /**
+     * Returns the bar
+     * @return the bar
+     */
+    public int getBar() { return 0; }
+
+    /**
+     * Returns the fiz
+     */
+    public int getFiz() { return 0; }
+    // violation above, '@return tag should be present and have description.'
+
+    /**
+     * Returns the baz
+     * @see "getFoo"
+     */
+    public int getBaz() { return 0; }
+    // violation above, '@return tag should be present and have description.'
+}