Work around apparent Checkstyle bug re. JavaDoc in package-info.java

We have earlier agreed to, and aligned our Checkstyle rules accordingly,
not enforce JavaDoc presence, just validate its content if it's present.
However, we are still enforcing every package-info.java (of which we
have almost none..) to have a JavaDoc.

While experimenting with plastering package-info.java into EVERY package
everywhere (to have an annotation @NonNullByDefault package in it..),
I don't want to put in bogus empty JavaDoc into every package just to
satisfy Checkstyle, that would be ridiculous.

Related to https://github.com/checkstyle/checkstyle/issues/3416

Change-Id: I397763f9e09bc7db009ade5da1a5b35bdc518169
Signed-off-by: Michael Vorburger <vorburger@redhat.com>

diff --git a/checkstyle/src/main/resources/odl_checks.xml b/checkstyle/src/main/resources/odl_checks.xml
index bda2a12feb223fc2f347bee44c5eaa7d5cea3ad4..cecba405260fb2359f0e264525e165814ac5c2b8 100644 (file)
--- a/checkstyle/src/main/resources/odl_checks.xml
+++ b/checkstyle/src/main/resources/odl_checks.xml
@@ -226,6 +226,16 @@
         <module name="JavadocStyle">
             <!-- Do NOT 'scope' this one; any JavaDoc (public/protected/private) IFF present, should be style checked. -->
             <property name="checkEmptyJavadoc" value="true" />
+            <!-- All except PACKAGE_DEF, due to a Checkstyle particularity (bug?):
+                 For all tokens, JavadocStyle checks JavaDoc compliance IFF present;
+                 only for package-info.java this ENFORCES that there is a JavaDoc
+                 in each package-info.java.  We believe this to be a bug because
+                 JavadocPackage seems to be inteded for enforcement.  Therefore,
+                 in line with not enforcing JavaDoc everywhere, just checking when
+                 it's present, we must therefore customize the tokens list here.
+                 see https://github.com/checkstyle/checkstyle/issues/3416
+             -->
+            <property name="tokens" value="ANNOTATION_DEF, ANNOTATION_FIELD_DEF, CLASS_DEF, CTOR_DEF, ENUM_CONSTANT_DEF, ENUM_DEF, INTERFACE_DEF, METHOD_DEF, VARIABLE_DEF"/>
         </module>
         <module name="MethodName">
             <property name="format" value="^[a-z][a-zA-Z0-9_]*$"/>