Document that <annotationProcessorPaths> is the preferred way to use …

…auto-value for Maven and Gradle. Fixes #773. RELNOTES=Document that `<annotationProcessorPaths>` is the preferred way to use auto-value for Maven and Gradle. ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=275036598
google · Oct 17, 2019 · 7dc5450 · 7dc5450
1 parent 78eef20
commit 7dc5450
Show file tree

Hide file tree

Showing 2 changed files with 50 additions and 21 deletions.
diff --git a/service/README.md b/service/README.md
@@ -56,7 +56,6 @@ In Maven, you can write:
     <groupId>com.google.auto.service</groupId>
     <artifactId>auto-service-annotations</artifactId>
     <version>${auto-service.version}</version>
-    <optional>true</optional>
   </dependency>
 </dependencies>
 
@@ -79,7 +78,8 @@ In Maven, you can write:
 ```
 
 Alternatively, you can include the processor itself (which transitively depends
-on the annotation) in your compile-time classpath:
+on the annotation) in your compile-time classpath. (However, note that doing so
+may pull unnecessary classes into your runtime classpath.)
 
 ```xml
 <dependencies>

diff --git a/value/userguide/index.md b/value/userguide/index.md
@@ -74,36 +74,65 @@ have Javadoc. We're leaving these off in the User Guide only to keep the
 examples short and simple.
 
 
-### In `pom.xml`
+### With Maven
 
-Maven users should add the following to the project's `pom.xml` file:
+You will need `auto-value-annotations-${version}.jar` in your compile-time
+classpath, and you will need `auto-value-${version}.jar` in your
+annotation-processor classpath.
+
+In `pom.xml`, you can write:
+
+```xml
+<dependencies>
+  <dependency>
+    <groupId>com.google.auto.value</groupId>
+    <artifactId>auto-value-annotations</artifactId>
+    <version>${auto-value.version}</version>
+  </dependency>
+</dependencies>
+
+...
+
+<plugins>
+  <plugin>
+    <artifactId>maven-compiler-plugin</artifactId>
+    <configuration>
+      <annotationProcessorPaths>
+        <path>
+          <groupId>com.google.auto.value</groupId>
+          <artifactId>auto-value</artifactId>
+          <version>${auto-value.version}</version>
+        </path>
+      </annotationProcessorPaths>
+    </configuration>
+  </plugin>
+</plugins>
+```
+
+Alternatively, you can include the processor itself (which transitively depends
+on the annotation) in your compile-time classpath. (However, note that doing so
+may pull unnecessary classes into your runtime classpath.)
 
 ```xml
-<dependency>
-  <groupId>com.google.auto.value</groupId>
-  <artifactId>auto-value-annotations</artifactId>
-  <version>1.6.6</version>
-</dependency>
-<dependency>
-  <groupId>com.google.auto.value</groupId>
-  <artifactId>auto-value</artifactId>
-  <version>1.6.6</version>
-  <scope>provided</scope>
-</dependency>
+<dependencies>
+  <dependency>
+    <groupId>com.google.auto.value</groupId>
+    <artifactId>auto-value</artifactId>
+    <version>${version}</version>
+    <optional>true</optional>
+  </dependency>
+</dependencies>
 ```
 
-Alternatively, instead of using the `provided` scope, you can add the second
-dependency to the
-[`annotationProcessorPaths`](https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#annotationProcessorPaths)
-section.
+### With Gradle
 
 Gradle users can declare the dependencies in their `build.gradle` script:
 
 ```groovy
 dependencies {
   // Use 'api' rather than 'compile' for Android or java-library projects.
-  compile             "com.google.auto.value:auto-value-annotations:1.6.6"
-  annotationProcessor "com.google.auto.value:auto-value:1.6.6"
+  compile             "com.google.auto.value:auto-value-annotations:${autoValueVersion}"
+  annotationProcessor "com.google.auto.value:auto-value:${autoValueVersion}"
 }
 ```