core,README: add docs about grpc-java-api-checker

[jyane]

No description provided.

[ericgribkoff]

Thanks for doing this! A couple comments below.

[ericgribkoff]

I think we want to aim this more at library code that uses gRPC, as they may have less control of the ultimate gRPC version that gets used than an application developer directly using gRPC. Something like:

APIs that are annotated with @ExperimentalApi are subject to change, and APIs that are annotated with @Internal are for internal use by the gRPC library. Because APIs with these annotations could be modified or even removed in a future release, library code that other projects may depend on should not use these APIs. We recommend using the grpc-java-api-checker (an Error Prone plugin) to check for usages of @ExperimentalApi and @Internal in any library code that depends on gRPC.

[jyane]

I thought all users should not use @Internal APIs. I respect your opinion :)

[ericgribkoff]

That's fair. We have the wording in @Internal's javadoc about using these APIs to implement a custom load balancer or transport, but that's probably fine to leave out here:

APIs annotated with @Internal are for internal use by the gRPC library and should not be used by gRPC users. APIs annotated with @ExperimentalApi are subject to change in future releases, and library code that other projects may depend on should not use these APIs. We recommend using the grpc-java-api-checker (an Error Prone plugin) to check for usages of @ExperimentalApi and @Internal in any library code that depends on gRPC. It may also be used to check for @Internal usage or unintended @ExperimentalApi consumption in non-library code.

Currently quite a lot of our APIs are marked experimental, so I think the "you should not use @ExperimentalApi" statement in the original text is too strong. @ejona86 WDYT?

[ejona86]

Oops, the load balancer reference is out-dated. Sent out #4192

Yeah, "not use" is too strong. For the library piece I think I'd say something closer to "Since libraries can not generally guarantee which version of gRPC is being used, most libraries should not use APIs annotated with @ExperimentalApi." But @ericgribkoff's most recent suggested text looks fine.

[jyane]

Thanks! I've fixed.

[ericgribkoff]

How about:

 * @see <a href="https://github.com/grpc/grpc/grpc-java-api-checker">grpc-java-api-checker</a>, an 
 * Error Prone plugin to automatically check for usages of this API.

(Same for Internal.java)

[jyane]

Done.

[jyane]

@ericgribkoff PTAL

[jyane]

Wait... checkstyles are failed... I will fix it.

[jyane]

I've fixed but I've found new warnings on :javadoc. (d76746a)

.:grpc-core:javadocPicked up _JAVA_OPTIONS: -Xmx2048m -Xms512m
/home/travis/build/grpc/grpc-java/core/src/main/java/io/grpc/ExperimentalApi.java:52: warning - Tag @see: missing final '>': "<a href="https://github.com/grpc/grpc-java-api-checker">grpc-java-api-checker</a>, an Error
     Prone plugin to automatically check for usages of this API."
/home/travis/build/grpc/grpc-java/core/src/main/java/io/grpc/Internal.java:48: warning - Tag @see: missing final '>': "<a href="https://github.com/grpc/grpc-java-api-checker">grpc-java-api-checker</a>, an Error
     Prone plugin to automatically check for usages of this API."

2 warnings

and It could be reproduced on my local machine.

$ ./gradlew :grpc-core:javadoc

> Configure project :grpc-compiler
*** Building codegen requires Protobuf version 3.5.1-1
*** Please refer to https://github.com/grpc/grpc-java/blob/master/COMPILING.md#how-to-build-code-generation-plugin

> Task :grpc-core:javadoc
/Users/jyane/workspace/repos/github.com/jyane/grpc-java/core/src/main/java/io/grpc/ExperimentalApi.java:52: warning - Tag @see: missing final '>': "<a href="https://github.com/grpc/grpc-java-api-checker">grpc-java-api-checker</a>, an Error
     Prone plugin to automatically check for usages of this API."
/Users/jyane/workspace/repos/github.com/jyane/grpc-java/core/src/main/java/io/grpc/Internal.java:49: warning - Tag @see: missing final '>': "<a href="https://github.com/grpc/grpc-java-api-checker">grpc-java-api-checker</a>, an Error
      Prone plugin to automatically check for usages of this API."
2 warnings


BUILD SUCCESSFUL in 4s
6 actionable tasks: 1 executed, 5 up-to-date

Using a link with strings might not be permitted.
https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDDIEDI

Thus, I've removed @see. @ericgribkoff What do you think? I might be something wrong.

[ericgribkoff]

LGTM

[jyane]

I want to merge this PR once grpc-java-api-checker:1.1.0 was released.

ref: grpc/grpc-java-api-checker#15

[jyane]

Thanks!