From 4f0b42b0ab784c64dc60a1dfb51da785bc47e97b Mon Sep 17 00:00:00 2001
From: Kun Zhang <zhangkun@google.com>
Date: Fri, 28 Sep 2018 23:06:10 -0700
Subject: [PATCH 1/2] 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.
---
 .../alts/internal/AltsProtocolNegotiator.java  | 14 ++++----------
 .../internal/AltsProtocolNegotiatorTest.java   |  4 ++--
 .../src/main/java/io/grpc/CallCredentials.java |  2 ++
 core/src/main/java/io/grpc/ClientCall.java     |  3 ++-
 .../java/io/grpc/EquivalentAddressGroup.java   | 18 ++++++++++++++++++
 core/src/main/java/io/grpc/Grpc.java           | 17 +++++++++++++++++
 core/src/main/java/io/grpc/LoadBalancer.java   |  3 ++-
 core/src/main/java/io/grpc/NameResolver.java   | 18 +++++++++++++++++-
 core/src/main/java/io/grpc/ServerCall.java     |  4 +++-
 .../java/io/grpc/internal/GrpcAttributes.java  |  5 +++++
 10 files changed, 72 insertions(+), 16 deletions(-)

diff --git a/alts/src/main/java/io/grpc/alts/internal/AltsProtocolNegotiator.java b/alts/src/main/java/io/grpc/alts/internal/AltsProtocolNegotiator.java
index e182f98a296..cd598c86aa9 100644
--- a/alts/src/main/java/io/grpc/alts/internal/AltsProtocolNegotiator.java
+++ b/alts/src/main/java/io/grpc/alts/internal/AltsProtocolNegotiator.java
@@ -41,19 +41,13 @@
  */
 public abstract class AltsProtocolNegotiator implements ProtocolNegotiator {
 
-  private static final Attributes.Key<TsiPeer> TSI_PEER_KEY = Attributes.Key.create("TSI_PEER");
-  private static final Attributes.Key<AltsAuthContext> ALTS_CONTEXT_KEY =
+  @Grpc.TransportAttr
+  public static final Attributes.Key<TsiPeer> TSI_PEER_KEY = Attributes.Key.create("TSI_PEER");
+  @Grpc.TransportAttr
+  public static final Attributes.Key<AltsAuthContext> ALTS_CONTEXT_KEY =
       Attributes.Key.create("ALTS_CONTEXT_KEY");
   private static final AsciiString scheme = AsciiString.of("https");
 
-  public static Attributes.Key<TsiPeer> getTsiPeerAttributeKey() {
-    return TSI_PEER_KEY;
-  }
-
-  public static Attributes.Key<AltsAuthContext> getAltsAuthContextAttributeKey() {
-    return ALTS_CONTEXT_KEY;
-  }
-
   /** Creates a negotiator used for ALTS client. */
   public static AltsProtocolNegotiator createClientNegotiator(
       final TsiHandshakerFactory handshakerFactory) {
diff --git a/alts/src/test/java/io/grpc/alts/internal/AltsProtocolNegotiatorTest.java b/alts/src/test/java/io/grpc/alts/internal/AltsProtocolNegotiatorTest.java
index 44341e0c472..9745e2c001b 100644
--- a/alts/src/test/java/io/grpc/alts/internal/AltsProtocolNegotiatorTest.java
+++ b/alts/src/test/java/io/grpc/alts/internal/AltsProtocolNegotiatorTest.java
@@ -341,9 +341,9 @@ public void doNotFlushEmptyBuffer() throws Exception {
   public void peerPropagated() throws Exception {
     doHandshake();
 
-    assertThat(grpcHandler.attrs.get(AltsProtocolNegotiator.getTsiPeerAttributeKey()))
+    assertThat(grpcHandler.attrs.get(AltsProtocolNegotiator.TSI_PEER_KEY))
         .isEqualTo(mockedTsiPeer);
-    assertThat(grpcHandler.attrs.get(AltsProtocolNegotiator.getAltsAuthContextAttributeKey()))
+    assertThat(grpcHandler.attrs.get(AltsProtocolNegotiator.ALTS_CONTEXT_KEY))
         .isEqualTo(mockedAltsContext);
     assertThat(grpcHandler.attrs.get(Grpc.TRANSPORT_ATTR_REMOTE_ADDR).toString())
         .isEqualTo("embedded");
diff --git a/core/src/main/java/io/grpc/CallCredentials.java b/core/src/main/java/io/grpc/CallCredentials.java
index 7ce62199367..0d87bb61003 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 936cb322b6c..4ec41e1810d 100644
--- a/core/src/main/java/io/grpc/ClientCall.java
+++ b/core/src/main/java/io/grpc/ClientCall.java
@@ -262,7 +262,8 @@ public void setMessageCompression(boolean enabled) {
    * 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.
+   * <p>Keys that it may contain are annotated with {@link Grpc.TransportAttr} by convention, but
+   * they are not guaranteed to be present.
    *
    * @return non-{@code null} attributes
    * @throws IllegalStateException (optional) if called before permitted
diff --git a/core/src/main/java/io/grpc/EquivalentAddressGroup.java b/core/src/main/java/io/grpc/EquivalentAddressGroup.java
index 2218a7fae65..8bcb0affbe0 100644
--- a/core/src/main/java/io/grpc/EquivalentAddressGroup.java
+++ b/core/src/main/java/io/grpc/EquivalentAddressGroup.java
@@ -17,6 +17,11 @@
 package io.grpc;
 
 import com.google.common.base.Preconditions;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 import java.net.SocketAddress;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -28,6 +33,9 @@
  * <p>Usually the addresses are addresses resolved from the same host name, and connecting to any of
  * them is equally sufficient. They do have order. An address appears earlier on the list is likely
  * to be tried earlier.
+ *
+ * <p>An {@code EquivalentAddressGroup} object is associated with an {@link Attributes} object.
+ * Keys that it may contain are annotated with {@link EquivalentAddressGroup.Attr} by convention.
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1770")
 public final class EquivalentAddressGroup {
@@ -127,4 +135,14 @@ public boolean equals(Object other) {
     }
     return true;
   }
+
+  /**
+   * Annotates keys that may appear in the attributes of an {@link EquivalentAddressGroup}.
+   *
+   * <p>Click "USE" on the navigation bars of the javadoc page to see annotated keys.
+   */
+  @Retention(RetentionPolicy.SOURCE)
+  @Documented
+  @Target(ElementType.FIELD)
+  public @interface Attr {}
 }
diff --git a/core/src/main/java/io/grpc/Grpc.java b/core/src/main/java/io/grpc/Grpc.java
index aef07260621..c81369b1497 100644
--- a/core/src/main/java/io/grpc/Grpc.java
+++ b/core/src/main/java/io/grpc/Grpc.java
@@ -16,6 +16,11 @@
 
 package io.grpc;
 
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 import java.net.SocketAddress;
 import javax.net.ssl.SSLSession;
 
@@ -31,6 +36,7 @@ private 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 +44,17 @@ private 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 attribute Keys.
+   *
+   * <p>Click "USE" on the navigation bars of the javadoc page to see annotated keys.
+   */
+  @Retention(RetentionPolicy.SOURCE)
+  @Documented
+  @Target(ElementType.FIELD)
+  public @interface TransportAttr {}
 }
diff --git a/core/src/main/java/io/grpc/LoadBalancer.java b/core/src/main/java/io/grpc/LoadBalancer.java
index 9256ea81033..8c1b1227005 100644
--- a/core/src/main/java/io/grpc/LoadBalancer.java
+++ b/core/src/main/java/io/grpc/LoadBalancer.java
@@ -107,7 +107,8 @@ 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.  Keys that it may contain are
+   *                   annotated with {@link NameResolver.ResolutionResultAttr} by convention.
    * @since 1.2.0
    */
   public abstract void handleResolvedAddressGroups(
diff --git a/core/src/main/java/io/grpc/NameResolver.java b/core/src/main/java/io/grpc/NameResolver.java
index 60f819e4d1a..d100683cdcd 100644
--- a/core/src/main/java/io/grpc/NameResolver.java
+++ b/core/src/main/java/io/grpc/NameResolver.java
@@ -16,6 +16,11 @@
 
 package io.grpc;
 
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 import java.net.URI;
 import java.util.List;
 import javax.annotation.Nullable;
@@ -134,7 +139,8 @@ public interface Listener {
      * <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.  Keys that it may contain are
+     *                   annotated with {@link ResolutionResultAttr} by convention.
      * @since 1.3.0
      */
     void onAddresses(List<EquivalentAddressGroup> servers, Attributes attributes);
@@ -148,4 +154,14 @@ public interface Listener {
      */
     void onError(Status error);
   }
+
+  /**
+   * Annotation for attribute keys for name resolution result.
+   *
+   * <p>Click "USE" on the navigation bars of the javadoc page to see annotated keys.
+   */
+  @Retention(RetentionPolicy.SOURCE)
+  @Documented
+  @Target(ElementType.FIELD)
+  public @interface ResolutionResultAttr {}
 }
diff --git a/core/src/main/java/io/grpc/ServerCall.java b/core/src/main/java/io/grpc/ServerCall.java
index 106676fa7a7..749607bd85f 100644
--- a/core/src/main/java/io/grpc/ServerCall.java
+++ b/core/src/main/java/io/grpc/ServerCall.java
@@ -192,7 +192,9 @@ public void setCompression(String compressor) {
    * 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.
+   *
+   * <p>Keys that it may contain are annotated with {@link Grpc.TransportAttr} by convention, but
+   * they are not guaranteed to be present.
    *
    * @return non-{@code null} Attributes container
    */
diff --git a/core/src/main/java/io/grpc/internal/GrpcAttributes.java b/core/src/main/java/io/grpc/internal/GrpcAttributes.java
index 67da06fa771..e620bb6d714 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");
 

From 026538516c8911b6c3b5e00da0294a894eaffd9a Mon Sep 17 00:00:00 2001
From: Kun Zhang <zhangkun@google.com>
Date: Sat, 29 Sep 2018 14:58:01 -0700
Subject: [PATCH 2/2] Expand the usage of annotations to Attributes variables.

---
 core/src/main/java/io/grpc/Attributes.java       | 12 ++++++++++++
 core/src/main/java/io/grpc/ClientCall.java       |  4 +---
 .../java/io/grpc/EquivalentAddressGroup.java     | 16 +++++-----------
 core/src/main/java/io/grpc/Grpc.java             |  8 ++------
 core/src/main/java/io/grpc/LoadBalancer.java     |  6 +++---
 core/src/main/java/io/grpc/NameResolver.java     | 14 +++++---------
 core/src/main/java/io/grpc/ServerCall.java       |  4 +---
 7 files changed, 29 insertions(+), 35 deletions(-)

diff --git a/core/src/main/java/io/grpc/Attributes.java b/core/src/main/java/io/grpc/Attributes.java
index 9a13f5160e1..411d11c3371 100644
--- a/core/src/main/java/io/grpc/Attributes.java
+++ b/core/src/main/java/io/grpc/Attributes.java
@@ -29,6 +29,18 @@
 
 /**
  * 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/ClientCall.java b/core/src/main/java/io/grpc/ClientCall.java
index 4ec41e1810d..2aa5034b7b7 100644
--- a/core/src/main/java/io/grpc/ClientCall.java
+++ b/core/src/main/java/io/grpc/ClientCall.java
@@ -262,13 +262,11 @@ public void setMessageCompression(boolean enabled) {
    * or {@link Listener#onClose}. If called prematurely, the implementation may throw {@code
    * IllegalStateException} or return arbitrary {@code Attributes}.
    *
-   * <p>Keys that it may contain are annotated with {@link Grpc.TransportAttr} by convention, 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 8bcb0affbe0..916e4a00a62 100644
--- a/core/src/main/java/io/grpc/EquivalentAddressGroup.java
+++ b/core/src/main/java/io/grpc/EquivalentAddressGroup.java
@@ -18,10 +18,8 @@
 
 import com.google.common.base.Preconditions;
 import java.lang.annotation.Documented;
-import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
 import java.net.SocketAddress;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -33,9 +31,6 @@
  * <p>Usually the addresses are addresses resolved from the same host name, and connecting to any of
  * them is equally sufficient. They do have order. An address appears earlier on the list is likely
  * to be tried earlier.
- *
- * <p>An {@code EquivalentAddressGroup} object is associated with an {@link Attributes} object.
- * Keys that it may contain are annotated with {@link EquivalentAddressGroup.Attr} by convention.
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1770")
 public final class EquivalentAddressGroup {
@@ -58,7 +53,7 @@ public EquivalentAddressGroup(List<SocketAddress> addrs) {
   /**
    * 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");
@@ -77,7 +72,7 @@ public EquivalentAddressGroup(SocketAddress addr) {
   /**
    * Singleton constructor with Attributes.
    */
-  public EquivalentAddressGroup(SocketAddress addr, Attributes attrs) {
+  public EquivalentAddressGroup(SocketAddress addr, @Attr Attributes attrs) {
     this(Collections.singletonList(addr), attrs);
   }
 
@@ -91,6 +86,7 @@ public List<SocketAddress> getAddresses() {
   /**
    * Returns the attributes.
    */
+  @Attr
   public Attributes getAttributes() {
     return attrs;
   }
@@ -137,12 +133,10 @@ public boolean equals(Object other) {
   }
 
   /**
-   * Annotates keys that may appear in the attributes of an {@link EquivalentAddressGroup}.
-   *
-   * <p>Click "USE" on the navigation bars of the javadoc page to see annotated keys.
+   * Annotation for {@link EquivalentAddressGroup}'s attributes. It follows the annotation semantics
+   * defined by {@link Attributes}.
    */
   @Retention(RetentionPolicy.SOURCE)
   @Documented
-  @Target(ElementType.FIELD)
   public @interface Attr {}
 }
diff --git a/core/src/main/java/io/grpc/Grpc.java b/core/src/main/java/io/grpc/Grpc.java
index c81369b1497..4884a57ebe5 100644
--- a/core/src/main/java/io/grpc/Grpc.java
+++ b/core/src/main/java/io/grpc/Grpc.java
@@ -17,10 +17,8 @@
 package io.grpc;
 
 import java.lang.annotation.Documented;
-import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
 import java.net.SocketAddress;
 import javax.net.ssl.SSLSession;
 
@@ -49,12 +47,10 @@ private Grpc() {
           Attributes.Key.create("ssl-session");
 
   /**
-   * Annotation for transport attribute Keys.
-   *
-   * <p>Click "USE" on the navigation bars of the javadoc page to see annotated keys.
+   * Annotation for transport attributes. It follows the annotation semantics defined
+   * by {@link Attributes}.
    */
   @Retention(RetentionPolicy.SOURCE)
   @Documented
-  @Target(ElementType.FIELD)
   public @interface TransportAttr {}
 }
diff --git a/core/src/main/java/io/grpc/LoadBalancer.java b/core/src/main/java/io/grpc/LoadBalancer.java
index 8c1b1227005..f1cef63fba2 100644
--- a/core/src/main/java/io/grpc/LoadBalancer.java
+++ b/core/src/main/java/io/grpc/LoadBalancer.java
@@ -107,12 +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 information from naming system.  Keys that it may contain are
-   *                   annotated with {@link NameResolver.ResolutionResultAttr} by convention.
+   * @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 d100683cdcd..03767ca108b 100644
--- a/core/src/main/java/io/grpc/NameResolver.java
+++ b/core/src/main/java/io/grpc/NameResolver.java
@@ -17,10 +17,8 @@
 package io.grpc;
 
 import java.lang.annotation.Documented;
-import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
 import java.net.URI;
 import java.util.List;
 import javax.annotation.Nullable;
@@ -139,11 +137,11 @@ public interface Listener {
      * <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 information from naming system.  Keys that it may contain are
-     *                   annotated with {@link ResolutionResultAttr} by convention.
+     * @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
@@ -156,12 +154,10 @@ public interface Listener {
   }
 
   /**
-   * Annotation for attribute keys for name resolution result.
-   *
-   * <p>Click "USE" on the navigation bars of the javadoc page to see annotated keys.
+   * Annotation for name resolution result attributes. It follows the annotation semantics defined
+   * by {@link Attributes}.
    */
   @Retention(RetentionPolicy.SOURCE)
   @Documented
-  @Target(ElementType.FIELD)
   public @interface ResolutionResultAttr {}
 }
diff --git a/core/src/main/java/io/grpc/ServerCall.java b/core/src/main/java/io/grpc/ServerCall.java
index 749607bd85f..07711e381d1 100644
--- a/core/src/main/java/io/grpc/ServerCall.java
+++ b/core/src/main/java/io/grpc/ServerCall.java
@@ -193,12 +193,10 @@ public void setCompression(String compressor) {
    *
    * <p>Attributes originate from the transport and can be altered by {@link ServerTransportFilter}.
    *
-   * <p>Keys that it may contain are annotated with {@link Grpc.TransportAttr} by convention, 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;
   }