From 5af2515f3ea55bdbf65a3e96bf664ab2e4e5678e Mon Sep 17 00:00:00 2001
From: Shohei Kamimori <jyane.kstm@gmail.com>
Date: Thu, 29 Mar 2018 07:34:18 +0900
Subject: [PATCH] core,README: add docs about grpc-java-api-checker (#4182)

---
 README.md                                       | 13 +++++++++++++
 core/src/main/java/io/grpc/ExperimentalApi.java |  3 +++
 core/src/main/java/io/grpc/Internal.java        |  3 +++
 3 files changed, 19 insertions(+)

diff --git a/README.md b/README.md
index de0e422db8..1aacf3b2a9 100644
--- a/README.md
+++ b/README.md
@@ -239,3 +239,16 @@ The [examples](https://github.com/grpc/grpc-java/tree/master/examples)
 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 5a04789517..10b253e112 100644
--- a/core/src/main/java/io/grpc/ExperimentalApi.java
+++ b/core/src/main/java/io/grpc/ExperimentalApi.java
@@ -36,6 +36,9 @@ import java.lang.annotation.Target;
  *
  * <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 b65ee8dca4..e2c56bc113 100644
--- a/core/src/main/java/io/grpc/Internal.java
+++ b/core/src/main/java/io/grpc/Internal.java
@@ -32,6 +32,9 @@ import java.lang.annotation.Target;
  *
  * <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({