WIP: Generate documentation

(Manual run with `mvn exec:java@generate-bugpattern-docs -pl refaster-runner`.)

TODO: Actually hook this up in a website

error-prone-contrib/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>tech.picnic.error-prone-support</groupId>
         <artifactId>error-prone-support</artifactId>
-        <version>0.7.0</version>
+        <version>0.7.1-SNAPSHOT</version>
     </parent>
 
     <artifactId>error-prone-contrib</artifactId>
@@ -242,5 +242,11 @@
                 </plugin>
             </plugins>
         </pluginManagement>
+        <plugins>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
     </build>
 </project>

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/MapRules.java

@@ -1,5 +1,7 @@
 package tech.picnic.errorprone.refasterrules;
 
+import static java.util.Objects.requireNonNullElse;
+
 import com.google.errorprone.refaster.Refaster;
 import com.google.errorprone.refaster.annotation.AfterTemplate;
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
@@ -43,6 +45,21 @@ final class MapRules {
     }
   }
 
+  /** Prefer {@link Map#getOrDefault(Object, Object)} over more contrived alternatives. */
+  // XXX: Note that `requireNonNullElse` throws an NPE if the second argument is `null`, while the
+  // alternative does not.
+  static final class MapGetOrDefault<K, V, T> {
+    @BeforeTemplate
+    V before(Map<K, V> map, T key, V defaultValue) {
+      return requireNonNullElse(map.get(key), defaultValue);
+    }
+
+    @AfterTemplate
+    V after(Map<K, V> map, T key, V defaultValue) {
+      return map.getOrDefault(key, defaultValue);
+    }
+  }
+
   /** Prefer {@link Map#isEmpty()} over more contrived alternatives. */
   static final class MapIsEmpty<K, V> {
     @BeforeTemplate

error-prone-contrib/src/test/resources/tech/picnic/errorprone/refasterrules/MapRulesTestInput.java

@@ -1,5 +1,7 @@
 package tech.picnic.errorprone.refasterrules;
 
+import static java.util.Objects.requireNonNullElse;
+
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import java.math.RoundingMode;
@@ -11,7 +13,7 @@ import tech.picnic.errorprone.refaster.test.RefasterRuleCollectionTestCase;
 final class MapRulesTest implements RefasterRuleCollectionTestCase {
   @Override
   public ImmutableSet<?> elidedTypesAndStaticImports() {
-    return ImmutableSet.of(HashMap.class);
+    return ImmutableSet.of(HashMap.class, requireNonNullElse(null, null));
   }
 
   Map<RoundingMode, String> testCreateEnumMap() {
@@ -22,6 +24,10 @@ final class MapRulesTest implements RefasterRuleCollectionTestCase {
     return ImmutableMap.of(1, "foo").getOrDefault("bar", null);
   }
 
+  String testMapGetOrDefault() {
+    return requireNonNullElse(ImmutableMap.of(1, "foo").get("bar"), "baz");
+  }
+
   ImmutableSet<Boolean> testMapIsEmpty() {
     return ImmutableSet.of(
         ImmutableMap.of("foo", 1).keySet().isEmpty(),

error-prone-contrib/src/test/resources/tech/picnic/errorprone/refasterrules/MapRulesTestOutput.java

@@ -1,5 +1,7 @@
 package tech.picnic.errorprone.refasterrules;
 
+import static java.util.Objects.requireNonNullElse;
+
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import java.math.RoundingMode;
@@ -12,7 +14,7 @@ import tech.picnic.errorprone.refaster.test.RefasterRuleCollectionTestCase;
 final class MapRulesTest implements RefasterRuleCollectionTestCase {
   @Override
   public ImmutableSet<?> elidedTypesAndStaticImports() {
-    return ImmutableSet.of(HashMap.class);
+    return ImmutableSet.of(HashMap.class, requireNonNullElse(null, null));
   }
 
   Map<RoundingMode, String> testCreateEnumMap() {
@@ -23,6 +25,10 @@ final class MapRulesTest implements RefasterRuleCollectionTestCase {
     return ImmutableMap.of(1, "foo").get("bar");
   }
 
+  String testMapGetOrDefault() {
+    return ImmutableMap.of(1, "foo").getOrDefault("bar", "baz");
+  }
+
   ImmutableSet<Boolean> testMapIsEmpty() {
     return ImmutableSet.of(
         ImmutableMap.of("foo", 1).isEmpty(),

pom.xml

@@ -4,7 +4,7 @@
 
     <groupId>tech.picnic.error-prone-support</groupId>
     <artifactId>error-prone-support</artifactId>
-    <version>0.7.0</version>
+    <version>0.7.1-SNAPSHOT</version>
     <packaging>pom</packaging>
 
     <name>Picnic :: Error Prone Support</name>
@@ -48,7 +48,7 @@
 
     <scm>
         <developerConnection>scm:git:git@github.com:PicnicSupermarket/error-prone-support.git</developerConnection>
-        <tag>v0.7.0</tag>
+        <tag>HEAD</tag>
         <url>https://github.com/PicnicSupermarket/error-prone-support</url>
     </scm>
     <issueManagement>
@@ -810,6 +810,11 @@
                                 <artifactId>error_prone_core</artifactId>
                                 <version>${version.error-prone}</version>
                             </path>
+                            <path>
+                                <groupId>${groupId.error-prone}</groupId>
+                                <artifactId>error_prone_docgen_processor</artifactId>
+                                <version>${version.error-prone}</version>
+                            </path>
                             <path>
                                 <groupId>com.google.auto.value</groupId>
                                 <artifactId>auto-value</artifactId>
@@ -1089,6 +1094,37 @@
                     <artifactId>build-helper-maven-plugin</artifactId>
                     <version>3.3.0</version>
                 </plugin>
+                <plugin>
+                    <groupId>org.codehaus.mojo</groupId>
+                    <artifactId>exec-maven-plugin</artifactId>
+                    <version>3.0.0</version>
+                    <configuration>
+                        <mainClass>com.google.errorprone.DocGenTool</mainClass>
+                        <arguments>
+                            <argument>-bug_patterns=${project.build.directory}/generated-sources/annotations/bugPatterns.txt</argument>
+                            <argument>-docs_repository=${project.build.directory}/generated-wiki/</argument>
+                            <argument>-explanations=${basedir}/src/main/docs/bugpattern/</argument>
+                            <argument>-target=external</argument>
+                        </arguments>
+                        <includePluginDependencies>true</includePluginDependencies>
+                    </configuration>
+                    <dependencies>
+                        <dependency>
+                            <groupId>com.google.errorprone</groupId>
+                            <artifactId>error_prone_docgen</artifactId>
+                            <version>${version.error-prone}</version>
+                        </dependency>
+                    </dependencies>
+                    <executions>
+                        <execution>
+                            <id>generate-bugpattern-docs</id>
+                            <goals>
+                                <goal>java</goal>
+                            </goals>
+                            <phase>process-classes</phase>
+                        </execution>
+                    </executions>
+                </plugin>
                 <plugin>
                     <groupId>org.codehaus.mojo</groupId>
                     <artifactId>license-maven-plugin</artifactId>

refaster-compiler/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>tech.picnic.error-prone-support</groupId>
         <artifactId>error-prone-support</artifactId>
-        <version>0.7.0</version>
+        <version>0.7.1-SNAPSHOT</version>
     </parent>
 
     <artifactId>refaster-compiler</artifactId>

refaster-runner/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>tech.picnic.error-prone-support</groupId>
         <artifactId>error-prone-support</artifactId>
-        <version>0.7.0</version>
+        <version>0.7.1-SNAPSHOT</version>
     </parent>
 
     <artifactId>refaster-runner</artifactId>

refaster-runner/src/main/docs/bugpattern/Refaster.md

@@ -0,0 +1,16 @@
+Error Prone's out-of-the-box support for the application of
+[Refaster][refaster] templates is somewhat cumbersome. Additionally, by default
+the focus of Refaster templates is on one-off code refactorings.
+
+This plugin attempts to bring Refaster templates on equal footing with other
+Error Prone plugins by locating all Refaster templates on the classpath and
+reporing any match. The suggested changes can be applied using Error Prone's
+built-in [patch][patching] functionality.
+
+XXX: Expand documentation. Mention:
+- The `refaster-resource-compiler`.
+- How checks can be restricted using the `NamePattern` flag (see the Javadoc)
+- An concrete patching example, with and without `NamePattern`.
+
+[refaster]: https://errorprone.info/docs/refaster
+[patching]: https://errorprone.info/docs/patching

refaster-support/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>tech.picnic.error-prone-support</groupId>
         <artifactId>error-prone-support</artifactId>
-        <version>0.7.0</version>
+        <version>0.7.1-SNAPSHOT</version>
     </parent>
 
     <artifactId>refaster-support</artifactId>

refaster-test-support/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>tech.picnic.error-prone-support</groupId>
         <artifactId>error-prone-support</artifactId>
-        <version>0.7.0</version>
+        <version>0.7.1-SNAPSHOT</version>
     </parent>
 
     <artifactId>refaster-test-support</artifactId>