How to disable checkstyle JavaDoc validation for constructors?

Question

How to disable checkstyle JavaDoc validation for constructors?

I see that http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod states clearly that it "Checks the Javadoc of a method or constructor", however I need to exclude constructors and leave only methods.

Caskey

Answer 1

In order to ignore constructors, remove the CTOR_DEF token from the tokens property, for example:

<module name="JavadocMethod">
  <property name="tokens" value="METHOD_DEF,ANNOTATION_FIELD_DEF"/>
</module>

This is achieved by setting tokens to all the other allowed tokens except CTOR_DEF. Unfortunately, for this to work, you need to know which tokens to set, and this list varies by Checkstyle version and is not always accurately reflected in the docs. This above example should provide a reasonable setting.

Poland

The default values for JavadocMethod include CTOR_DEF, METHOD_DEF and ANNOTATION_FIELD_DEF. Of these 3, CTOR_DEF is responsible for Constructors - so you should remove only that and put the other two viz. METHOD_DEF and ANNOTATION_FIELD_DEF instead of just METHOD_DEF. – Niche

@Niche You are right, answer updated. Thanks! In my defense, the additional token was not on the list when I wrote the original answer. ;-) – Poland

@ThomasJensen For this to work I had to use "target" as the name of the property instead of "tokens" as you mentioned it. – Myth

@Myth Interesting - I can't find a property called target on this check, even in the oldest or newest versions of Checkstyle. Sure that there is no mixup of some kind? – Poland

Answer 2

Ignore javadocs only on constructors with a custom class...

<module name="org.example.MyJavadocMethodCheck">
...
</module>

which looks like:

@SuppressWarnings("unused")
public class MyJavadocMethodCheck extends com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocMethodCheck {

    @Override
    public int[] getAcceptableTokens() {
        return Arrays.stream(super.getAcceptableTokens())
            .filter(t -> t != TokenTypes.CTOR_DEF) // Don't enforce javadoc comments on constructors
            .toArray();
    }
}

I'm sure I found this on stackoverflow but can't find the exact link anymore.

Moua

This is basically correct, but way too complicated. The check has a tokens property to configure this behavior. No need for a custom check. – Poland

The amount of code with a custom class is indeed more. The only benefit here is that I don't need to know "all the other allowed" values when using "tokens" (METHOD_DEF,ANNOTATION_FIELD_DEF ...) but rather exclude just the one(s) I'm interested in (CTOR_DEF). – Moua

Answer 3

Since Checkstyle version 3.21, to ignore Javadocs for constructors you need to use MissingJavadocMethod module, with the property tokens set to METHOD_DEF , ANNOTATION_FIELD_DEF , COMPACT_CTOR_DEF:

<module name="MissingJavadocMethod">
  <property name="allowMissingPropertyJavadoc" value="true"/>
  <property name="tokens" value="METHOD_DEF , ANNOTATION_FIELD_DEF , COMPACT_CTOR_DEF "/>
</module>

For more information about the MissingJavadocMethod module: https://checkstyle.sourceforge.io/config_javadoc.html

Slowpoke

It's weird that you answered this 2014 when Checkstyle 3.x was the newest version. Now, 2023, Checkstyle 10.x is the newest version and checkstyle.org/checks/javadoc/… states that the MissingJavadocMethod module exists since 8.21. Anyway, it helped me. – Ossian

The question is dated from 2015, I answered the question on 14 of March this year :) – Slowpoke

Oh damn, you're right. My bad, hehe. So you're not from the future after all. – Ossian