Re-add the doc changes that describe behavior of using nulls

Author: bidetofevil

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

@@ -35,11 +35,15 @@ public interface AttributesBuilder {
   // version.
   <T> AttributesBuilder put(AttributeKey<Long> key, int value);
 
-  /** Puts a {@link AttributeKey} with associated value into this. */
+  /**
+   * 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.
+   */
   <T> AttributesBuilder put(AttributeKey<T> key, T value);
 
   /**
-   * Puts a String attribute into this.
+   * Puts a String attribute into this if the value is non-null. Providing a null value does not
+   * remove or unset previously set values.
    *
    * <p>Note: It is strongly recommended to use {@link #put(AttributeKey, Object)}, and pre-allocate
    * your keys, if possible.

api/all/src/main/java/io/opentelemetry/api/logs/LogRecordBuilder.java

@@ -107,6 +107,8 @@ default LogRecordBuilder setAllAttributes(Attributes attributes) {
    * Sets an attribute on the {@code LogRecord}. If the {@code LogRecord} previously contained a
    * mapping for the key, the old value is replaced by the specified value.
    *
+   * <p>Note: Providing a null value is a no-op and will not remove previously set values.
+   *
    * @param key the key for this attribute.
    * @param value the value for this attribute.
    * @return this.
@@ -117,6 +119,8 @@ default LogRecordBuilder setAllAttributes(Attributes attributes) {
    * Sets a String attribute on the {@code LogRecord}. If the {@code LogRecord} previously contained
    * a mapping for the key, the old value is replaced by the specified value.
    *
+   * <p>Note: Providing a null value is a no-op and will not remove previously set values.
+   *
    * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
    * pre-allocate your keys, if possible.
    *

api/all/src/main/java/io/opentelemetry/api/trace/Span.java

@@ -88,7 +88,9 @@ static Span wrap(SpanContext spanContext) {
    * Sets an attribute to the {@code Span}. If the {@code Span} previously contained a mapping for
    * the key, the old value is replaced by the specified value.
    *
-   * <p>Empty String "" and null are valid attribute {@code value}, but not valid keys.
+   * <p>Empty String "" and null are valid attribute {@code value}s, but not valid keys.
+   *
+   * <p>Note: Providing a null value is a no-op and will not remove previously set values.
    *
    * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
    * pre-allocate your keys, if possible.
@@ -150,7 +152,7 @@ default Span setAttribute(String key, boolean value) {
    * Sets an attribute to the {@code Span}. If the {@code Span} previously contained a mapping for
    * the key, the old value is replaced by the specified value.
    *
-   * <p>Note: the behavior of null values is undefined, and hence strongly discouraged.
+   * <p>Note: Providing a null value is a no-op.
    *
    * @param key the key for this attribute.
    * @param value the value for this attribute.