From 7dc5450ec1abdd6473a5dd11dcb19f4115ff7a89 Mon Sep 17 00:00:00 2001
From: dpb <dpb@google.com>
Date: Wed, 16 Oct 2019 08:25:35 -0700
Subject: [PATCH] Document that <annotationProcessorPaths> is the preferred way
 to use auto-value for Maven and Gradle.

Fixes https://github.com/google/auto/issues/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
---
 service/README.md        |  4 +--
 value/userguide/index.md | 67 ++++++++++++++++++++++++++++------------
 2 files changed, 50 insertions(+), 21 deletions(-)

diff --git a/service/README.md b/service/README.md
index dd9251fae1..5016456135 100644
--- 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
index 085b149d63..6984e2b882 100644
--- 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}"
 }
 ```