Documentation should prefer specifying annotation processor paths

[netdpb]

https://github.com/google/auto/blob/master/value/userguide/index.md#in-pomxml first suggests to use <provided>true</provided> on the Maven dependency, and then suggests configuring <annotationProcessorPaths> as an alternative.

We should switch the priority of those (for all artifacts). Using <provided>true</provided> puts the annotation processor and its dependencies on the compile-time and runtime classpath, and could lead to linkage errors at runtime (e.g., googleapis/java-core#46).

[cpovirk]

Coincidentally, I updated the AutoService docs in this way just a few days ago. My immediate motivation there was an additional advantage of using the annotation-processor path: As soon as you set one annotation-processor path in your project (for example, for Error Prone, even though that's a plugin rather than a true(?) annotation processor), javac requires you to do them all that way. (It's also nice to be able to avoid optional/provided for the annotations artifact, at which point you're stuck adding separate entries for the annotations and the processor, so you might as well do it "right" :))

[netdpb]

Can we just do the same thing for all the auto* projects?

[cpovirk]

I think we should. I'm not sure that AutoFactory has separate annotation and processor artifacts yet, so that would be step 1 for it.

[netdpb]

OK, so this issue can cover that whole effort.

[cpovirk]

Also, filed GoogleCloudPlatform/cloud-opensource-java#986 to see if it's worth recommending this pattern in our best practices.