add reasons for suppressed warnings

Author: zeitlinger

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

@@ -41,7 +41,7 @@ public AttributesBuilder toBuilder() {
     return new ArrayBackedAttributesBuilder(new ArrayList<>(data()));
   }
 
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // entries are typed as Object[]
   @Override
   @Nullable
   public <T> T get(AttributeKey<T> key) {

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

@@ -48,7 +48,7 @@ public <T> AttributesBuilder put(AttributeKey<T> key, @Nullable T value) {
   }
 
   @Override
-  @SuppressWarnings({"unchecked", "rawtypes"})
+  @SuppressWarnings({"unchecked", "rawtypes"}) // using "put" method with raw type AttributeKey
   public AttributesBuilder putAll(Attributes attributes) {
     if (attributes == null) {
       return this;

api/all/src/main/java/io/opentelemetry/api/internal/ImmutableKeyValuePairs.java

@@ -71,7 +71,7 @@ public final Map<K, V> asMap() {
 
   /** Returns the value for the given {@code key}, or {@code null} if the key is not present. */
   @Nullable
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // data is typed as Object[]
   public final V get(K key) {
     if (key == null) {
       return null;
@@ -85,7 +85,7 @@ public final V get(K key) {
   }
 
   /** Iterates over all the key-value pairs of labels contained by this instance. */
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // data is typed as Object[]
   public final void forEach(BiConsumer<? super K, ? super V> consumer) {
     if (consumer == null) {
       return;
@@ -150,7 +150,7 @@ private static void splitAndMerge(
    * Left source half is sourceArray[ beginIndex:middleIndex-1]. Right source half is sourceArray[
    * middleIndex:endIndex-1]. Result is targetArray[ beginIndex:endIndex-1].
    */
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // sourceArray and targetArray is typed as Object[]
   private static <K> void merge(
       Object[] sourceArray,
       int beginIndex,
@@ -192,7 +192,7 @@ private static <K> int compareToNullSafe(
     return keyComparator.compare(key, pivotKey);
   }
 
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // data is typed as Object[]
   private static <K> Object[] dedupe(Object[] data, Comparator<K> keyComparator) {
     Object previousKey = null;
     int size = 0;

api/all/src/main/java/io/opentelemetry/api/internal/IncubatingUtil.java

@@ -18,7 +18,7 @@
 public class IncubatingUtil {
   private IncubatingUtil() {}
 
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // casting to T
   public static <T> T incubatingApiIfAvailable(T stableApi, String incubatingClassName) {
     try {
       Class<?> incubatingClass = Class.forName(incubatingClassName);

api/all/src/main/java/io/opentelemetry/api/internal/ReadOnlyArrayMap.java

@@ -37,7 +37,7 @@
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.
  */
-@SuppressWarnings("unchecked")
+@SuppressWarnings("unchecked") // array is typed as List<Object>
 public final class ReadOnlyArrayMap<K, V> extends AbstractMap<K, V> {
 
   /** Returns a read-only view of the given {@code array}. */

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

@@ -94,7 +94,7 @@ default LogRecordBuilder setBody(Value<?> body) {
    * Sets attributes. If the {@link LogRecordBuilder} previously contained a mapping for any of the
    * keys, the old values are replaced by the specified values.
    */
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // use of raw AttributeKey
   default LogRecordBuilder setAllAttributes(Attributes attributes) {
     if (attributes == null || attributes.isEmpty()) {
       return this;

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

@@ -54,7 +54,7 @@ public void forEach(BiConsumer<String, String> consumer) {
   }
 
   @Override
-  @SuppressWarnings({"unchecked", "rawtypes"})
+  @SuppressWarnings({"unchecked", "rawtypes"}) // wrap takes List<Object>
   public Map<String, String> asMap() {
     return ReadOnlyArrayMap.wrap((List) getEntries());
   }

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

@@ -180,7 +180,7 @@ default Span setAttribute(AttributeKey<Long> key, int value) {
    * @return this.
    * @since 1.2.0
    */
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // use of raw AttributeKey
   default Span setAllAttributes(Attributes attributes) {
     if (attributes == null || attributes.isEmpty()) {
       return this;

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

@@ -259,7 +259,7 @@ default SpanBuilder setAttribute(AttributeKey<Long> key, int value) {
    * @return this.
    * @since 1.2.0
    */
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // use of raw AttributeKey
   default SpanBuilder setAllAttributes(Attributes attributes) {
     if (attributes == null || attributes.isEmpty()) {
       return this;

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

@@ -47,14 +47,14 @@ public ExtendedAttributesBuilder toBuilder() {
     return new ArrayBackedExtendedAttributesBuilder(new ArrayList<>(data()));
   }
 
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // cast to T
   @Override
   @Nullable
   public <T> T get(ExtendedAttributeKey<T> key) {
     return (T) super.get(key);
   }
 
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // use of raw ExtendedAttributeKey
   @Override
   public Attributes asAttributes() {
     if (attributes == null) {