Since Checkstyle 3.0
Checks the Javadoc of a method or constructor.
Violates parameters and type parameters
for which no param tags are
present can be suppressed by defining property
allowMissingParamTags
.
Violates methods which return non-void but for which no return tag is
present can be suppressed by defining property
allowMissingReturnTag
.
Violates exceptions which are declared to be thrown (by throws
in the method
signature or by throw new
in the method body), but for which no throws tag is
present by activation of property validateThrows
.
Note that throw new
is not checked in the following places:
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).
Javadoc is not required on a method that is tagged with the
@Override
annotation. However, under
Java 5 it is not possible to mark a method required for an
interface (this was corrected under Java 6). Hence,
Checkstyle supports using the convention of using a single
{@inheritDoc}
tag instead of all the
other tags.
Note that only inheritable items will allow the
{@inheritDoc}
tag to be used in place
of comments. Static methods at all visibilities, private non-static
methods and constructors are not inheritable.
For example, if the following method is implementing a method required by an interface, then the Javadoc could be done as:
/** {@inheritDoc} */ public int checkReturnTag(final int aTagIndex, JavadocTag[] aTags, int aLineNo)
name | description | type | default value | since |
---|---|---|---|---|
accessModifiers | Specify the access modifiers where Javadoc comments are checked. | AccessModifierOption[] | public, protected, package, private |
8.42 |
allowMissingParamTags | Control whether to ignore violations when a method has parameters but does not have matching param tags in the javadoc. |
boolean | false |
3.1 |
allowMissingReturnTag | Control whether to ignore violations when a method returns non-void type and does not have a return tag in the javadoc. |
boolean | false |
3.1 |
allowedAnnotations | Specify annotations that allow missed documentation. | String[] | Override |
6.0 |
validateThrows | Control whether to validate throws tags. |
boolean | false |
6.0 |
tokens | tokens to check | subset of tokens METHOD_DEF , CTOR_DEF , ANNOTATION_FIELD_DEF , COMPACT_CTOR_DEF . | METHOD_DEF , CTOR_DEF , ANNOTATION_FIELD_DEF , COMPACT_CTOR_DEF . | 3.0 |
To configure the default check:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocMethod"/> </module> </module>
Example:
public class Test { /** * */ Test(int x) { // violation, param tag missing for x } /** * */ public int foo(int p1) { // violation, param tag missing for p1 return p1; // violation, return tag missing } /** * * @param p1 The first number */ @Deprecated private int boo(int p1) { return p1; // violation, return tag missing } /** * */ void bar(int p1) { // violation, param tag missing for p1 } // ok, no return tag for void method }
To configure the check for only public
modifier, ignoring any missing param tags is:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocMethod"> <property name="accessModifiers" value="public"/> <property name="allowMissingParamTags" value="true"/> </module> </module> </module>
Example:
public class Test { /** * */ Test(int x) { // ok, only public methods checked } /** * */ public int foo(int p1) { // ok, missing param tags allowed return p1; // violation, return tag missing } /** * * @param p1 The first number */ @Deprecated private int boo(int p1) { return p1; // ok, only public methods checked } /** * */ void bar(int p1) { // ok, missing param tags allowed } // ok, no return tag for void method }
To configure the check for methods which are in private
and
package
, but not any other modifier:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocMethod"> <property name="accessModifiers" value="private, package"/> </module> </module> </module>
Example:
class Test { /** * */ Test(int x) { // violation, param tag missing for x } /** * */ public int foo(int p1) { // ok, public methods not checked return p1; } /** * * @param p1 The first number */ @Deprecated private int boo(int p1) { return p1; // violation, return tag missing } /** * */ void bar(int p1) { // violation, param tag missing for p1 } // ok, no return tag for void method }
To configure the check to ignore any missing return tags:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocMethod"> <property name="allowMissingReturnTag" value="true"/> </module> </module> </module>
Example:
public class Test { /** * */ Test(int x) { // violation, param tag missing for x } /** * */ public int foo(int p1) { // violation, param tag missing for p1 return p1; // ok, missing return tag allowed } /** * * @param p1 The first number */ @Deprecated private int boo(int p1) { return p1; // ok, missing return tag allowed } /** * */ void bar(int p1) { // violation, param tag missing for p1 } // ok, no return tag for void method }
To configure the check to ignore Methods with annotation Deprecated
:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocMethod"> <property name="allowedAnnotations" value="Deprecated"/> </module> </module> </module>
Example:
public class Test { /** * */ Test(int x) { // violation, param tag missing for x } /** * */ public int foo(int p1) { // violation, param tag missing for p1 return p1; // violation, return tag missing } /** * * @param p1 The first number */ @Deprecated private int boo(int p1) { return p1; // ok, Deprecated methods not checked } /** * */ void bar(int p1) { // violation, param tag missing for p1 } // ok, no return tag for void method }
To configure the check only for tokens which are Constructor Definitions:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocMethod"> <property name="tokens" value="CTOR_DEF"/> </module> </module> </module>
Example:
public class Test { /** * */ Test(int x) { // violation, param tag missing for x } /** * */ public int foo(int p1) { // ok, method not checked return p1; // ok, method not checked } /** * * @param p1 The first number */ @Deprecated private int boo(int p1) { return p1; // ok, method not checked } /** * */ void bar(int p1) { // ok, method not checked } }
To configure the check to validate throws
tags, you can use following config.
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocMethod"> <property name="validateThrows" value="true"/> </module> </module> </module>
Example:
/** * 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. * @param file some file * @throws IOException if some problem */ public void doSomething8(File file) throws IOException { if (file == null) { throw new FileNotFoundException(); // violation } } /** * 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. * @param file some file * @throws IOException if some problem * @throws FileNotFoundException if file is not found */ public void doSomething9(File file) throws IOException { if (file == null) { throw new FileNotFoundException(); } } /** * Ignore try block, but keep catch and finally blocks. * * @param s String to parse * @return A positive integer */ public int parsePositiveInt(String s) { try { int value = Integer.parseInt(s); if (value <= 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 } } /** * Try block without catch is not ignored. * * @return a String from standard input, if there is one */ public String readLine() { try (Scanner sc = new Scanner(System.in)) { if (!sc.hasNext()) { throw new IllegalStateException("Empty input"); // violation, not caught } return sc.next(); } } /** * Lambda expressions are ignored as we do not know when the exception will be thrown. * * @param s a String to be printed at some point in the future * @return a Runnable to be executed when the string is to be printed */ public Runnable printLater(String s) { return () -> { if (s == null) { throw new NullPointerException(); // ok } System.out.println(s); }; }
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.javadoc