Failure in JavaDocMethod - Need Help!

[nitishfy]

I'm working on this issue in which I've understood the check well along with examples to be provided.

In the following documentation on JavDocMethod on which examples needs to be added (https://checkstyle.org/config_javadoc.html#JavadocMethod), the second line in the description says Violates parameters and type parameters for which no param tags are present can be suppressed by defining property allowMissingParamTags..

Apart from adding examples to the example section, I found that it'd be much better if there could be a simple example that can be put inside the Description block to explain the 2nd and 3rd lines of the documentation.

I tried adding some basic example as you can see below:

After running mvn clean verify , I received this error:

I'm aware of the fact that there JavaDoc should match with .XML configuration (Here, JavadocMethod.xml). I'm not able to find out what is the change that needs to be done in JavadocMethod.xml in order to prevent this error.

JavadocMethod.xml:

<?xml version="1.0" encoding="UTF-8"?>
<checkstyle-metadata>
   <module>
      <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocMethodCheck"
              name="JavadocMethod"
              parent="com.puppycrawl.tools.checkstyle.TreeWalker">
         <description>&lt;p&gt;
 Checks the Javadoc of a method or constructor.
 &lt;/p&gt;
 &lt;p&gt;
 Violates parameters and type parameters for which no param tags are present can
 be suppressed by defining property {@code allowMissingParamTags}.
 &lt;pre&gt;
public class Test {
     &amp;#47;**
      * Method to print sum of two numbers
      * &amp;#64;param
      * &amp;#64;param
      * &amp;#64;return A integer value
      *&amp;#47;
static int sum(int a,int b){ // method of non-void type
       return a+b;  // return statement is used
       }
 }
 &lt;/pre&gt;
 &lt;/p&gt;
 &lt;p&gt;
 Violates methods which return non-void but for which no return tag is present can
 be suppressed by defining property {@code allowMissingReturnTag}.
 &lt;/p&gt;
 &lt;p&gt;
 Violates exceptions which are declared to be thrown (by {@code throws} in the method
 signature or by {@code throw new} in the method body), but for which no throws tag is
 present by activation of property {@code validateThrows}.
 Note that {@code throw new} is not checked in the following places:
 &lt;/p&gt;
 &lt;ul&gt;
 &lt;li&gt;
 Inside a try block (with catch). It is not possible to determine if the thrown
 exception can be caught by the catch block as there is no knowledge of the
 inheritance hierarchy, so the try block is ignored entirely. However, catch
 and finally blocks, as well as try blocks without catch, are still checked.
 &lt;/li&gt;
 &lt;li&gt;
 Local classes, anonymous classes and lambda expressions. It is not known when the
 throw statements inside such classes are going to be evaluated, so they are ignored.
 &lt;/li&gt;
 &lt;/ul&gt;
 &lt;p&gt;
 ATTENTION: Checkstyle does not have information about hierarchy of exception types
 so usage of base class is considered as separate exception type.
 As workaround, you need to specify both types in javadoc (parent and exact type).
 &lt;/p&gt;
 &lt;p&gt;
 Javadoc is not required on a method that is tagged with the {@code @Override}
 annotation. However, under Java 5 it is not possible to mark a method required
 for an interface (this was &lt;i&gt;corrected&lt;/i&gt; under Java 6). Hence, Checkstyle
 supports using the convention of using a single {@code {@inheritDoc}} tag
 instead of all the other tags.
 &lt;/p&gt;
 &lt;p&gt;
 Note that only inheritable items will allow the {@code {@inheritDoc}}
 tag to be used in place of comments. Static methods at all visibilities,
 private non-static methods and constructors are not inheritable.
 &lt;/p&gt;
 &lt;p&gt;
 For example, if the following method is implementing a method required by
 an interface, then the Javadoc could be done as:
 &lt;/p&gt;
 &lt;pre&gt;
 &amp;#47;** {&amp;#64;inheritDoc} *&amp;#47;
 public int checkReturnTag(final int aTagIndex,
                           JavadocTag[] aTags,
                           int aLineNo)
 &lt;/pre&gt;</description>
         <properties>
            <property default-value="Override"
                       name="allowedAnnotations"
                       type="java.lang.String[]">
               <description>Specify annotations that allow missed documentation.</description>
            </property>
            <property default-value="false" name="validateThrows" type="boolean">
               <description>Control whether to validate {@code throws} tags.</description>
            </property>
            <property default-value="public, protected, package, private"
                       name="accessModifiers"
                       type="com.puppycrawl.tools.checkstyle.checks.naming.AccessModifierOption[]">
               <description>Specify the access modifiers where Javadoc comments are
 checked.</description>
            </property>
            <property default-value="false" name="allowMissingParamTags" type="boolean">
               <description>Control whether to ignore violations
 when a method has parameters but does not have matching {@code param} tags in the javadoc.</description>
            </property>
            <property default-value="false" name="allowMissingReturnTag" type="boolean">
               <description>Control whether to ignore violations
 when a method returns non-void type and does not have a {@code return} tag in the javadoc.</description>
            </property>
            <property default-value="METHOD_DEF,CTOR_DEF,ANNOTATION_FIELD_DEF,COMPACT_CTOR_DEF"
                       name="tokens"
                       type="java.lang.String[]"
                       validation-type="tokenSet">
               <description>tokens to check</description>
            </property>
         </properties>
         <message-keys>
            <message-key key="javadoc.classInfo"/>
            <message-key key="javadoc.duplicateTag"/>
            <message-key key="javadoc.expectedTag"/>
            <message-key key="javadoc.invalidInheritDoc"/>
            <message-key key="javadoc.return.expected"/>
            <message-key key="javadoc.unusedTag"/>
            <message-key key="javadoc.unusedTagGeneral"/>
         </message-keys>
      </check>
   </module>
</checkstyle-metadata>

JavaDoc in JavadocMethod.java

/**
 * <p>
 * Checks the Javadoc of a method or constructor.
 * </p>
 * <p>
 * Violates parameters and type parameters for which no param tags are present can
 * be suppressed by defining property {@code allowMissingParamTags}.
 * <pre>
 *public class Test {
 *     &#47;**
 *      * Method to print sum of two numbers
 *      * &#64;param
 *      * &#64;param
 *      * &#64;return A integer value
 *      *&#47;
 *static int sum(int a,int b){ // method of non-void type
 *       return a+b;  // return statement is used
 *       }
 * }
 * </pre>
 * </p>
 * <p>
 * Violates methods which return non-void but for which no return tag is present can
 * be suppressed by defining property {@code allowMissingReturnTag}.
 * </p>
 * <p>
 * Violates exceptions which are declared to be thrown (by {@code throws} in the method
 * signature or by {@code throw new} in the method body), but for which no throws tag is
 * present by activation of property {@code validateThrows}.
 * Note that {@code throw new} is not checked in the following places:
 * </p>
 * <ul>
 * <li>
 * Inside a try block (with catch). It is not possible to determine if the thrown
 * exception can be caught by the catch block as there is no knowledge of the
 * inheritance hierarchy, so the try block is ignored entirely. However, catch
 * and finally blocks, as well as try blocks without catch, are still checked.
 * </li>
 * <li>
 * Local classes, anonymous classes and lambda expressions. It is not known when the
 * throw statements inside such classes are going to be evaluated, so they are ignored.
 * </li>
 * </ul>
 * <p>
 * ATTENTION: Checkstyle does not have information about hierarchy of exception types
 * so usage of base class is considered as separate exception type.
 * As workaround, you need to specify both types in javadoc (parent and exact type).
 * </p>
 * <p>
 * Javadoc is not required on a method that is tagged with the {@code @Override}
 * annotation. However, under Java 5 it is not possible to mark a method required
 * for an interface (this was <i>corrected</i> under Java 6). Hence, Checkstyle
 * supports using the convention of using a single {@code {@inheritDoc}} tag
 * instead of all the other tags.
 * </p>
 * <p>
 * Note that only inheritable items will allow the {@code {@inheritDoc}}
 * tag to be used in place of comments. Static methods at all visibilities,
 * private non-static methods and constructors are not inheritable.
 * </p>
 * <p>
 * For example, if the following method is implementing a method required by
 * an interface, then the Javadoc could be done as:
 * </p>
 * <pre>
 * &#47;** {&#64;inheritDoc} *&#47;
 * public int checkReturnTag(final int aTagIndex,
 *                           JavadocTag[] aTags,
 *                           int aLineNo)
 * </pre>
 * <ul>
 * <li>
 * Property {@code allowedAnnotations} - Specify annotations that allow missed documentation.
 * Type is {@code java.lang.String[]}.
 * Default value is {@code Override}.
 * </li>
 * <li>
 * Property {@code validateThrows} - Control whether to validate {@code throws} tags.
 * Type is {@code boolean}.
 * Default value is {@code false}.
 * </li>
 * <li>
 * Property {@code accessModifiers} - Specify the access modifiers where Javadoc comments are
 * checked.
 * Type is {@code com.puppycrawl.tools.checkstyle.checks.naming.AccessModifierOption[]}.
 * Default value is {@code public, protected, package, private}.
 * </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}.
 * Default value is {@code false}.
 * </li>
 * <li>
 * Property {@code allowMissingReturnTag} - Control whether to ignore violations
 * when a method returns non-void type and does not have a {@code return} tag in the javadoc.
 * Type is {@code boolean}.
 * Default value is {@code false}.
 * </li>
 * <li>
 * Property {@code tokens} - tokens to check
 * Type is {@code java.lang.String[]}.
 * Validation type is {@code tokenSet}.
 * Default value is:
 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">
 * METHOD_DEF</a>,
 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">
 * CTOR_DEF</a>,
 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_FIELD_DEF">
 * ANNOTATION_FIELD_DEF</a>,
 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#COMPACT_CTOR_DEF">
 * COMPACT_CTOR_DEF</a>.
 * </li>
 * </ul>
 * <p>
 * To configure the default check:
 * </p>
 * <pre>
 * &lt;module name="JavadocMethod"/&gt;
 * </pre>
 * <p>
 * To configure the check for only {@code public} modifier, ignoring any missing param tags is:
 * </p>
 * <pre>
 * &lt;module name="JavadocMethod"&gt;
 *   &lt;property name="accessModifiers" value="public"/&gt;
 *   &lt;property name="allowMissingParamTags" value="true"/&gt;
 * &lt;/module&gt;
 * </pre>
 * <p>
 * To configure the check for methods which are in {@code private} and {@code package},
 * but not any other modifier:
 * </p>
 * <pre>
 * &lt;module name="JavadocMethod"&gt;
 *   &lt;property name="accessModifiers" value="private, package"/&gt;
 * &lt;/module&gt;
 * </pre>
 * <p>
 * To configure the check to validate {@code throws} tags, you can use following config.
 * </p>
 * <pre>
 * &lt;module name="JavadocMethod"&gt;
 *   &lt;property name="validateThrows" value="true"/&gt;
 * &lt;/module&gt;
 * </pre>
 * <pre>
 * &#47;**
 *  * Actual exception thrown is child class of class that is declared in throws.
 *  * It is limitation of checkstyle (as checkstyle does not know type hierarchy).
 *  * Javadoc is valid not declaring FileNotFoundException
 *  * BUT checkstyle can not distinguish relationship between exceptions.
 *  * &#64;param file some file
 *  * &#64;throws IOException if some problem
 *  *&#47;
 * public void doSomething8(File file) throws IOException {
 *     if (file == null) {
 *         throw new FileNotFoundException(); // violation
 *     }
 * }
 *
 * &#47;**
 *  * Exact throw type referencing in javadoc even first is parent of second type.
 *  * It is a limitation of checkstyle (as checkstyle does not know type hierarchy).
 *  * This javadoc is valid for checkstyle and for javadoc tool.
 *  * &#64;param file some file
 *  * &#64;throws IOException if some problem
 *  * &#64;throws FileNotFoundException if file is not found
 *  *&#47;
 * public void doSomething9(File file) throws IOException {
 *     if (file == null) {
 *         throw new FileNotFoundException();
 *     }
 * }
 *
 * &#47;**
 *  * Ignore try block, but keep catch and finally blocks.
 *  *
 *  * &#64;param s String to parse
 *  * &#64;return A positive integer
 *  *&#47;
 * public int parsePositiveInt(String s) {
 *     try {
 *         int value = Integer.parseInt(s);
 *         if (value &lt;= 0) {
 *             throw new NumberFormatException(value + " is negative/zero"); // ok, try
 *         }
 *         return value;
 *     } catch (NumberFormatException ex) {
 *         throw new IllegalArgumentException("Invalid number", ex); // violation, catch
 *     } finally {
 *         throw new IllegalStateException("Should never reach here"); // violation, finally
 *     }
 * }
 *
 * &#47;**
 *  * Try block without catch is not ignored.
 *  *
 *  * &#64;return a String from standard input, if there is one
 *  *&#47;
 * public String readLine() {
 *     try (Scanner sc = new Scanner(System.in)) {
 *         if (!sc.hasNext()) {
 *             throw new IllegalStateException("Empty input"); // violation, not caught
 *         }
 *         return sc.next();
 *     }
 * }
 *
 * &#47;**
 *  * Lambda expressions are ignored as we do not know when the exception will be thrown.
 *  *
 *  * &#64;param s a String to be printed at some point in the future
 *  * &#64;return a Runnable to be executed when the string is to be printed
 *  *&#47;
 * public Runnable printLater(String s) {
 *     return () -&gt; {
 *         if (s == null) {
 *             throw new NullPointerException(); // ok
 *         }
 *         System.out.println(s);
 *     };
 * }
 * </pre>
 * <p>
 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
 * </p>
 * <p>
 * Violation Message Keys:
 * </p>
 * <ul>
 * <li>
 * {@code javadoc.classInfo}
 * </li>
 * <li>
 * {@code javadoc.duplicateTag}
 * </li>
 * <li>
 * {@code javadoc.expectedTag}
 * </li>
 * <li>
 * {@code javadoc.invalidInheritDoc}
 * </li>
 * <li>
 * {@code javadoc.return.expected}
 * </li>
 * <li>
 * {@code javadoc.unusedTag}
 * </li>
 * <li>
 * {@code javadoc.unusedTagGeneral}
 * </li>
 * </ul>
 *
 * @since 3.0
 */

Changes I've done: (in JavadocMethod.java):

* <pre>
 *public class Test {
 *     &#47;**
 *      * Method to print sum of two numbers
 *      * &#64;param
 *      * &#64;param
 *      * &#64;return A integer value
 *      *&#47;
 *static int sum(int a,int b){ // method of non-void type
 *       return a+b;  // return statement is used
 *       }
 * }
 * </pre>

Please help me to know what are the next steps that I should be focusing upon in order to resolve this error?

[romani]

We do not add examples in description.
Description will be used as metadata content field. It will be used by numerous tool and services to render this content. This content should be simple.

[nitishfy]

Would it be a good way if we can shift the line 2 and 3 in the examples section?

[romani]

I don't understand, please send PR