Add javadoc explaining coersion

Author: trask

api/all/src/main/java/io/opentelemetry/api/common/AttributesBuilder.java

@@ -14,7 +14,6 @@
 import static io.opentelemetry.api.common.AttributeKey.longKey;
 import static io.opentelemetry.api.common.AttributeKey.stringArrayKey;
 import static io.opentelemetry.api.common.AttributeKey.stringKey;
-import static io.opentelemetry.api.common.AttributeKey.valueKey;
 
 import java.util.Arrays;
 import java.util.List;
@@ -40,6 +39,32 @@ public interface AttributesBuilder {
   /**
    * Puts an {@link AttributeKey} with an associated value into this if the value is non-null.
    * Providing a null value does not remove or unset previously set values.
+   *
+   * <p>Note: when passing a key of type {@link AttributeType#VALUE}, the call will be coerced into
+   * a narrower type if possible.
+   *
+   * <ul>
+   *   <li>Calling {@code put(AttributeKey.valueKey("key"), Value.of("a"))} is equivalent to calling
+   *       {@code put(AttributeKey.stringKey("key"), "a")}.
+   *   <li>Calling {@code put(AttributeKey.valueKey("key"), Value.of(1L))} is equivalent to calling
+   *       {@code put(AttributeKey.longKey("key"), 1L)}.
+   *   <li>Calling {@code put(AttributeKey.valueKey("key"), Value.of(1.0))} is equivalent to calling
+   *       {@code put(AttributeKey.doubleKey("key"), 1.0)}.
+   *   <li>Calling {@code put(AttributeKey.valueKey("key"), Value.of(true))} is equivalent to
+   *       calling {@code put(AttributeKey.booleanKey("key"), true)}.
+   *   <li>Calling {@code put(AttributeKey.valueKey("key"), Value.of(Value.of("a"), Value.of("b")))}
+   *       is equivalent to calling {@code put(AttributeKey.stringArrayKey("key"),
+   *       Arrays.asList("a", "b"))}.
+   *   <li>Calling {@code put(AttributeKey.valueKey("key"), Value.of(Value.of(1L), Value.of(2L)))}
+   *       is equivalent to calling {@code put(AttributeKey.longArrayKey("key"), Arrays.asList(1L,
+   *       2L))}.
+   *   <li>Calling {@code put(AttributeKey.valueKey("key"), Value.of(Value.of(1.0), Value.of(2.0)))}
+   *       is equivalent to calling {@code put(AttributeKey.doubleArrayKey("key"),
+   *       Arrays.asList(1.0, 2.0))}.
+   *   <li>Calling {@code put(AttributeKey.valueKey("key"), Value.of(Value.of(true),
+   *       Value.of(false)))} is equivalent to calling {@code
+   *       put(AttributeKey.booleanArrayKey("key"), Arrays.asList(true, false))}.
+   * </ul>
    */
   <T> AttributesBuilder put(AttributeKey<T> key, @Nullable T value);