Move warning to where users will see it

Author: trask

api/incubator/src/main/java/io/opentelemetry/api/incubator/common/ExtendedAttributeKey.java

@@ -106,7 +106,18 @@ static ExtendedAttributeKey<ExtendedAttributes> extendedAttributesKey(String key
     return InternalExtendedAttributeKeyImpl.create(key, ExtendedAttributeType.EXTENDED_ATTRIBUTES);
   }
 
-  /** Returns a new ExtendedAttributeKey for {@link Value} valued attributes. */
+  /**
+   * Returns a new ExtendedAttributeKey for {@link Value} valued attributes.
+   *
+   * <p>Simple attributes ({@link ExtendedAttributeType#STRING}, {@link ExtendedAttributeType#LONG},
+   * {@link ExtendedAttributeType#DOUBLE}, {@link ExtendedAttributeType#BOOLEAN}, {@link
+   * ExtendedAttributeType#STRING_ARRAY}, {@link ExtendedAttributeType#LONG_ARRAY}, {@link
+   * ExtendedAttributeType#DOUBLE_ARRAY}, {@link ExtendedAttributeType#BOOLEAN_ARRAY}) SHOULD be
+   * used whenever possible. Instrumentations SHOULD assume that backends do not index individual
+   * properties of complex attributes, that querying or aggregating on such properties is
+   * inefficient and complicated, and that reporting complex attributes carries higher performance
+   * overhead.
+   */
   static ExtendedAttributeKey<Value<?>> valueKey(String key) {
     return InternalExtendedAttributeKeyImpl.create(key, ExtendedAttributeType.VALUE);
   }

api/incubator/src/main/java/io/opentelemetry/api/incubator/common/ExtendedAttributeType.java

@@ -30,15 +30,5 @@ public enum ExtendedAttributeType {
    */
   @Deprecated
   EXTENDED_ATTRIBUTES,
-  /**
-   * Simple attributes ({@link ExtendedAttributeType#STRING}, {@link ExtendedAttributeType#LONG},
-   * {@link ExtendedAttributeType#DOUBLE}, {@link ExtendedAttributeType#BOOLEAN}, {@link
-   * ExtendedAttributeType#STRING_ARRAY}, {@link ExtendedAttributeType#LONG_ARRAY}, {@link
-   * ExtendedAttributeType#DOUBLE_ARRAY}, {@link ExtendedAttributeType#BOOLEAN_ARRAY}) SHOULD be
-   * used whenever possible. Instrumentations SHOULD assume that backends do not index individual
-   * properties of complex attributes, that querying or aggregating on such properties is
-   * inefficient and complicated, and that reporting complex attributes carries higher performance
-   * overhead.
-   */
   VALUE;
 }