core,README: add docs about grpc-java-api-checker (#4182)
diff --git a/README.md b/README.md
index de0e422..1aacf3b 100644
--- a/README.md
+++ b/README.md
@@ -239,3 +239,16 @@
and the
[Android example](https://github.com/grpc/grpc-java/tree/master/examples/android) are standalone projects that
showcase the usage of gRPC.
+
+Tools
+-----
+
+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](https://github.com/grpc/grpc-java-api-checker)
+(an [Error Prone](https://github.com/google/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.
diff --git a/core/src/main/java/io/grpc/ExperimentalApi.java b/core/src/main/java/io/grpc/ExperimentalApi.java
index 5a04789..10b253e 100644
--- a/core/src/main/java/io/grpc/ExperimentalApi.java
+++ b/core/src/main/java/io/grpc/ExperimentalApi.java
@@ -36,6 +36,9 @@
*
* <p>Note: This annotation is intended only for gRPC library code. Users should not attach this
* annotation to their own code.
+ *
+ * <p>See: <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.
*/
@Retention(RetentionPolicy.CLASS)
@Target({
diff --git a/core/src/main/java/io/grpc/Internal.java b/core/src/main/java/io/grpc/Internal.java
index b65ee8d..e2c56bc 100644
--- a/core/src/main/java/io/grpc/Internal.java
+++ b/core/src/main/java/io/grpc/Internal.java
@@ -32,6 +32,9 @@
*
* <p>Note: This annotation is intended only for gRPC library code. Users should not attach this
* annotation to their own code.
+ *
+ * <p>See: <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.
*/
@Retention(RetentionPolicy.CLASS)
@Target({
