Compile with (most off) -Xdoclint

error-prone-contrib/pom.xml

@@ -758,6 +758,21 @@
                     <plugin>
                         <groupId>org.apache.maven.plugins</groupId>
                         <artifactId>maven-compiler-plugin</artifactId>
+                        <executions>
+                            <execution>
+                                <id>default-testCompile</id>
+                                <phase>test-compile</phase>
+                                <goals>
+                                    <goal>testCompile</goal>
+                                </goals>
+                                <configuration>
+                                    <compilerArgs combine.children="append">
+                                        <!-- Test code doesn't require Javadoc. -->
+                                        <arg>-Xdoclint:-missing</arg>
+                                    </compilerArgs>
+                                </configuration>
+                            </execution>
+                        </executions>
                         <configuration>
                             <annotationProcessorPaths combine.children="append">
                                 <path>
@@ -767,6 +782,11 @@
                                 </path>
                             </annotationProcessorPaths>
                             <compilerArgs combine.children="append">
+                                <!-- We enable nearly all doclint checks,
+                                except that we don't care about missing Javadoc
+                                on non-public classes and members. -->
+                                <arg>-Xdoclint:all</arg>
+                                <arg>-Xdoclint:missing/protected</arg>
                                 <arg>-Xlint:all</arg>
                                 <!-- Not all annotations present on the
                                 classpath are handled by annotation processors,

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/AutowiredConstructorCheck.java

@@ -20,6 +20,7 @@ import com.sun.source.tree.MethodTree;
 import com.sun.tools.javac.code.Symbol;
 import com.sun.tools.javac.code.Symbol.MethodSymbol;
 
+/** A {@link BugChecker} which flags redundant {@code @Autowired} constructor annotations. */
 @AutoService(BugChecker.class)
 @BugPattern(
   name = "AutowiredConstructor",

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/CanonicalAnnotationSyntaxCheck.java

@@ -26,6 +26,7 @@ import java.util.function.BiFunction;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/** A {@link BugChecker} which flags annotations that could be written more concisely. */
 @AutoService(BugChecker.class)
 @BugPattern(
   name = "CanonicalAnnotationSyntax",

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/EmptyMethodCheck.java

@@ -10,6 +10,7 @@ import com.google.errorprone.bugpatterns.BugChecker.MethodTreeMatcher;
 import com.google.errorprone.matchers.Description;
 import com.sun.source.tree.MethodTree;
 
+/** A {@link BugChecker} which flags empty methods. */
 // XXX: Disable until fixed.
 // @AutoService(BugChecker.class)
 @BugPattern(

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/LexicographicalAnnotationAttributeListingCheck.java

@@ -30,8 +30,11 @@ import java.util.List;
 import java.util.Optional;
 import java.util.stream.Stream;
 
-// XXX: Add documentation. Explain that sorting reduces chances of conflicts and simplifies their
-// resolution when they do happen.
+/**
+ * A {@link BugChecker} which flags annotation array listings which aren't sorted lexicographically.
+ */
+// XXX: Add more documentation. Explain that sorting reduces chances of conflicts and simplifies
+// their resolution when they do happen.
 @AutoService(BugChecker.class)
 @BugPattern(
   name = "LexicographicalAnnotationAttributeListing",
@@ -50,10 +53,15 @@ public final class LexicographicalAnnotationAttributeListingCheck extends BugChe
 
   private final AnnotationAttributeMatcher matcher;
 
-  public LexicographicalAnnotationAttributeListingCheck() {
+  LexicographicalAnnotationAttributeListingCheck() {
     this(ErrorProneFlags.empty());
   }
 
+  /**
+   * Instantiates a customized {@link LexicographicalAnnotationAttributeListingCheck}.
+   *
+   * @param flags Any provided command line flags.
+   */
   public LexicographicalAnnotationAttributeListingCheck(ErrorProneFlags flags) {
     this.matcher = createAnnotationAttributeMatcher(flags);
   }

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/MethodMatcherFactory.java

@@ -12,7 +12,9 @@ import com.google.errorprone.matchers.Matcher;
 import com.sun.source.tree.ExpressionTree;
 import java.util.regex.Pattern;
 
-// XXX: Document.
+/** A method invocation expression {@link Matcher} factory. */
+// XXX: Document better. The expressions accepted here could also be defined using `MethodMatchers`.
+// So explain why this class is still useful.
 final class MethodMatcherFactory {
   private static final Splitter ARGUMENT_TYPE_SPLITTER =
       Splitter.on(',').trimResults().omitEmptyStrings();

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/MethodReferenceUsageCheck.java

@@ -35,6 +35,9 @@ import java.util.List;
 import java.util.Optional;
 import javax.lang.model.element.Name;
 
+/**
+ * A {@link BugChecker} which flags lambda expressions that can be replaced with method references.
+ */
 // XXX: Other custom expressions we could rewrite:
 // - `a -> "str" + a` to `"str"::concat`. But only if `str` is provably non-null.
 // - `(a, b) -> a + b` to `String::concat` or `{Integer,Long,Float,Double}::sum`. Also requires null

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/PrimitiveComparisonCheck.java

@@ -36,6 +36,10 @@ import java.util.function.ToLongFunction;
 import java.util.stream.Stream;
 import javax.annotation.CheckForNull;
 
+/**
+ * A {@link BugChecker} which flags {@code Comparator#comparing*} invocations that can be replaced
+ * with an equivalent alternative so as to avoid unnecessary (un)boxing.
+ */
 // XXX: Add more documentation. Explain how this is useful in the face of refactoring to more
 // specific types.
 // XXX: Change this checker's name?

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/RedundantStringConversionCheck.java

@@ -43,6 +43,7 @@ import java.util.Objects;
 import java.util.Optional;
 import java.util.regex.Pattern;
 
+/** A {@link BugChecker} which flags redundant explicit string conversions. */
 @AutoService(BugChecker.class)
 @BugPattern(
   name = "RedundantStringConversion",
@@ -155,10 +156,15 @@ public final class RedundantStringConversionCheck extends BugChecker
 
   private final Matcher<ExpressionTree> conversionMethodMatcher;
 
-  public RedundantStringConversionCheck() {
+  RedundantStringConversionCheck() {
     this(ErrorProneFlags.empty());
   }
 
+  /**
+   * Instantiates a customized {@link RedundantStringConversionCheck}.
+   *
+   * @param flags Any provided command line flags.
+   */
   public RedundantStringConversionCheck(ErrorProneFlags flags) {
     this.conversionMethodMatcher = createConversionMethodMatcher(flags);
   }

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/Slf4jLogStatementCheck.java

@@ -26,6 +26,7 @@ import java.util.List;
 import java.util.Optional;
 import java.util.regex.Pattern;
 
+/** A {@link BugChecker} which flags SLF4J usages that are likely to be in error. */
 // XXX: The special-casing of Throwable applies only to SLF4J 1.6.0+; see
 // https://www.slf4j.org/faq.html#paramException. That should be documented.
 // XXX: Also simplify `LOG.error(String.format("Something %s", arg), throwable)`.

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/SpringMvcAnnotationCheck.java

@@ -26,6 +26,10 @@ import com.sun.source.tree.NewArrayTree;
 import com.sun.source.tree.Tree.Kind;
 import java.util.Optional;
 
+/**
+ * A {@link BugChecker} which flags {@code @RequestMapping} annotations that can be written more
+ * concisely.
+ */
 @AutoService(BugChecker.class)
 @BugPattern(
   name = "SpringMvcAnnotation",

error-prone-contrib/src/main/java/com/picnicinternational/errorprone/bugpatterns/package-info.java

@@ -1,3 +1,4 @@
+/** Picnic Error Prone Contrib checks. */
 @com.google.errorprone.annotations.CheckReturnValue
 @javax.annotation.ParametersAreNonnullByDefault
 package com.picnicinternational.errorprone.bugpatterns;