doc: organize Attributes with annotations. (#4892)

* doc: organize Attributes Keys with annotations.

Keys are annotated with the following annotations:

1. Grpc.TransportAttr: transport attributes returned by
{Client,Server}Call.getAttributes().

2. NameResolver.ResolutionResultAttr: attributes passed as the
argument of NameResolver.Listener.onAddresses() and
LoadBalancer.handleResolvedAddressGroups()

3. EquivalentAddressGroup.Attr: attributes from
EquivalentAddressGroups.

* Expand the usage of annotations to Attributes variables.

9 files changed, 65 insertions, 9 deletions

diff --git a/core/src/main/java/io/grpc/Attributes.java b/core/src/main/java/io/grpc/Attributes.java
index 9a13f5160..411d11c33 100644
--- a/core/src/main/java/io/grpc/Attributes.java
+++ b/core/src/main/java/io/grpc/Attributes.java
@@ -29,6 +29,18 @@ import javax.annotation.concurrent.Immutable;
 
 /**
  * An immutable type-safe container of attributes.
+ *
+ * <h3>Annotation semantics</h3>
+ *
+ * <p>As a convention, annotations such as {@link Grpc.TransportAttr} is defined to associate
+ * attribute {@link Key}s and their propagation paths.  The annotation may be applied to a {@code
+ * Key} definition field, a method that returns {@link Attributes}, or a variable of type {@link
+ * Attributes}, to indicate that the annotated {@link Attributes} objects may contain the annotated
+ * {@code Key}.
+ *
+ * <p>Javadoc users may click "USE" on the navigation bars of the annotation's javadoc page to view
+ * references of such annotation.
+ *
  * @since 1.13.0
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1764")
diff --git a/core/src/main/java/io/grpc/CallCredentials.java b/core/src/main/java/io/grpc/CallCredentials.java
index 7ce621993..0d87bb610 100644
--- a/core/src/main/java/io/grpc/CallCredentials.java
+++ b/core/src/main/java/io/grpc/CallCredentials.java
@@ -42,6 +42,7 @@ public interface CallCredentials {
    * overridden by the transport.
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914")
+  @Grpc.TransportAttr
   public static final Key<SecurityLevel> ATTR_SECURITY_LEVEL =
       Key.create("io.grpc.CallCredentials.securityLevel");
 
@@ -52,6 +53,7 @@ public interface CallCredentials {
    * io.grpc.CallOptions} with increasing precedence.
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914")
+  @Grpc.TransportAttr
   public static final Key<String> ATTR_AUTHORITY = Key.create("io.grpc.CallCredentials.authority");
 
   /**
diff --git a/core/src/main/java/io/grpc/ClientCall.java b/core/src/main/java/io/grpc/ClientCall.java
index 936cb322b..2aa5034b7 100644
--- a/core/src/main/java/io/grpc/ClientCall.java
+++ b/core/src/main/java/io/grpc/ClientCall.java
@@ -262,12 +262,11 @@ public abstract class ClientCall<ReqT, RespT> {
    * or {@link Listener#onClose}. If called prematurely, the implementation may throw {@code
    * IllegalStateException} or return arbitrary {@code Attributes}.
    *
-   * <p>{@link Grpc} defines commonly used attributes, but they are not guaranteed to be present.
-   *
    * @return non-{@code null} attributes
    * @throws IllegalStateException (optional) if called before permitted
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2607")
+  @Grpc.TransportAttr
   public Attributes getAttributes() {
     return Attributes.EMPTY;
   }
diff --git a/core/src/main/java/io/grpc/EquivalentAddressGroup.java b/core/src/main/java/io/grpc/EquivalentAddressGroup.java
index 2218a7fae..916e4a00a 100644
--- a/core/src/main/java/io/grpc/EquivalentAddressGroup.java
+++ b/core/src/main/java/io/grpc/EquivalentAddressGroup.java
@@ -17,6 +17,9 @@
 package io.grpc;
 
 import com.google.common.base.Preconditions;
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.net.SocketAddress;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -50,7 +53,7 @@ public final class EquivalentAddressGroup {
   /**
    * List constructor with {@link Attributes}.
    */
-  public EquivalentAddressGroup(List<SocketAddress> addrs, Attributes attrs) {
+  public EquivalentAddressGroup(List<SocketAddress> addrs, @Attr Attributes attrs) {
     Preconditions.checkArgument(!addrs.isEmpty(), "addrs is empty");
     this.addrs = Collections.unmodifiableList(new ArrayList<>(addrs));
     this.attrs = Preconditions.checkNotNull(attrs, "attrs");
@@ -69,7 +72,7 @@ public final class EquivalentAddressGroup {
   /**
    * Singleton constructor with Attributes.
    */
-  public EquivalentAddressGroup(SocketAddress addr, Attributes attrs) {
+  public EquivalentAddressGroup(SocketAddress addr, @Attr Attributes attrs) {
     this(Collections.singletonList(addr), attrs);
   }
 
@@ -83,6 +86,7 @@ public final class EquivalentAddressGroup {
   /**
    * Returns the attributes.
    */
+  @Attr
   public Attributes getAttributes() {
     return attrs;
   }
@@ -127,4 +131,12 @@ public final class EquivalentAddressGroup {
     }
     return true;
   }
+
+  /**
+   * Annotation for {@link EquivalentAddressGroup}'s attributes. It follows the annotation semantics
+   * defined by {@link Attributes}.
+   */
+  @Retention(RetentionPolicy.SOURCE)
+  @Documented
+  public @interface Attr {}
 }
diff --git a/core/src/main/java/io/grpc/Grpc.java b/core/src/main/java/io/grpc/Grpc.java
index aef072606..4884a57eb 100644
--- a/core/src/main/java/io/grpc/Grpc.java
+++ b/core/src/main/java/io/grpc/Grpc.java
@@ -16,6 +16,9 @@
 
 package io.grpc;
 
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.net.SocketAddress;
 import javax.net.ssl.SSLSession;
 
@@ -31,6 +34,7 @@ public final class Grpc {
    * Attribute key for the remote address of a transport.
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1710")
+  @TransportAttr
   public static final Attributes.Key<SocketAddress> TRANSPORT_ATTR_REMOTE_ADDR =
           Attributes.Key.create("remote-addr");
 
@@ -38,6 +42,15 @@ public final class Grpc {
    * Attribute key for SSL session of a transport.
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1710")
+  @TransportAttr
   public static final Attributes.Key<SSLSession> TRANSPORT_ATTR_SSL_SESSION =
           Attributes.Key.create("ssl-session");
+
+  /**
+   * Annotation for transport attributes. It follows the annotation semantics defined
+   * by {@link Attributes}.
+   */
+  @Retention(RetentionPolicy.SOURCE)
+  @Documented
+  public @interface TransportAttr {}
 }
diff --git a/core/src/main/java/io/grpc/LoadBalancer.java b/core/src/main/java/io/grpc/LoadBalancer.java
index 9256ea810..f1cef63fb 100644
--- a/core/src/main/java/io/grpc/LoadBalancer.java
+++ b/core/src/main/java/io/grpc/LoadBalancer.java
@@ -107,11 +107,12 @@ public abstract class LoadBalancer {
    * <p>Implementations should not modify the given {@code servers}.
    *
    * @param servers the resolved server addresses, never empty.
-   * @param attributes extra metadata from naming system.
+   * @param attributes extra information from naming system.
    * @since 1.2.0
    */
   public abstract void handleResolvedAddressGroups(
-      List<EquivalentAddressGroup> servers, Attributes attributes);
+      List<EquivalentAddressGroup> servers,
+      @NameResolver.ResolutionResultAttr Attributes attributes);
 
   /**
    * Handles an error from the name resolution system.
diff --git a/core/src/main/java/io/grpc/NameResolver.java b/core/src/main/java/io/grpc/NameResolver.java
index 60f819e4d..03767ca10 100644
--- a/core/src/main/java/io/grpc/NameResolver.java
+++ b/core/src/main/java/io/grpc/NameResolver.java
@@ -16,6 +16,9 @@
 
 package io.grpc;
 
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.net.URI;
 import java.util.List;
 import javax.annotation.Nullable;
@@ -134,10 +137,11 @@ public abstract class NameResolver {
      * <p>Implementations will not modify the given {@code servers}.
      *
      * @param servers the resolved server addresses. An empty list will trigger {@link #onError}
-     * @param attributes extra metadata from naming system
+     * @param attributes extra information from naming system.
      * @since 1.3.0
      */
-    void onAddresses(List<EquivalentAddressGroup> servers, Attributes attributes);
+    void onAddresses(
+        List<EquivalentAddressGroup> servers, @ResolutionResultAttr Attributes attributes);
 
     /**
      * Handles an error from the resolver. The listener is responsible for eventually invoking
@@ -148,4 +152,12 @@ public abstract class NameResolver {
      */
     void onError(Status error);
   }
+
+  /**
+   * Annotation for name resolution result attributes. It follows the annotation semantics defined
+   * by {@link Attributes}.
+   */
+  @Retention(RetentionPolicy.SOURCE)
+  @Documented
+  public @interface ResolutionResultAttr {}
 }
diff --git a/core/src/main/java/io/grpc/ServerCall.java b/core/src/main/java/io/grpc/ServerCall.java
index 106676fa7..07711e381 100644
--- a/core/src/main/java/io/grpc/ServerCall.java
+++ b/core/src/main/java/io/grpc/ServerCall.java
@@ -192,11 +192,11 @@ public abstract class ServerCall<ReqT, RespT> {
    * Returns properties of a single call.
    *
    * <p>Attributes originate from the transport and can be altered by {@link ServerTransportFilter}.
-   * {@link Grpc} defines commonly used attributes, but they are not guaranteed to be present.
    *
    * @return non-{@code null} Attributes container
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1779")
+  @Grpc.TransportAttr
   public Attributes getAttributes() {
     return Attributes.EMPTY;
   }
diff --git a/core/src/main/java/io/grpc/internal/GrpcAttributes.java b/core/src/main/java/io/grpc/internal/GrpcAttributes.java
index 67da06fa7..e620bb6d7 100644
--- a/core/src/main/java/io/grpc/internal/GrpcAttributes.java
+++ b/core/src/main/java/io/grpc/internal/GrpcAttributes.java
@@ -17,6 +17,8 @@
 package io.grpc.internal;
 
 import io.grpc.Attributes;
+import io.grpc.EquivalentAddressGroup;
+import io.grpc.NameResolver;
 import java.util.Map;
 
 /**
@@ -26,6 +28,7 @@ public final class GrpcAttributes {
   /**
    * Attribute key for service config.
    */
+  @NameResolver.ResolutionResultAttr
   public static final Attributes.Key<Map<String, Object>> NAME_RESOLVER_SERVICE_CONFIG =
       Attributes.Key.create("service-config");
 
@@ -33,6 +36,7 @@ public final class GrpcAttributes {
    * The naming authority of a gRPC LB server address.  It is an address-group-level attribute,
    * present when the address group is a LoadBalancer.
    */
+  @EquivalentAddressGroup.Attr
   public static final Attributes.Key<String> ATTR_LB_ADDR_AUTHORITY =
       Attributes.Key.create("io.grpc.grpclb.lbAddrAuthority");
 
@@ -40,6 +44,7 @@ public final class GrpcAttributes {
    * Whether this EquivalentAddressGroup was provided by a GRPCLB server. It would be rare for this
    * value to be {@code false}; generally it would be better to not have the key present at all.
    */
+  @EquivalentAddressGroup.Attr
   public static final Attributes.Key<Boolean> ATTR_LB_PROVIDED_BACKEND =
       Attributes.Key.create("io.grpc.grpclb.lbProvidedBackend");