RUM-9902: post review fixes

Author: satween

features/dd-sdk-android-trace-api/src/main/kotlin/com/datadog/android/trace/api/scope/DataScopeListener.java

@@ -10,6 +10,8 @@
 public interface DataScopeListener {
   /**
    * Called just after a scope becomes the active scope.
+   * <p>May be called multiple times. When a scope is initially created, or after a child scope is
+   * deactivated.
    */
   void afterScopeActivated();
 

features/dd-sdk-android-trace-api/src/main/kotlin/com/datadog/android/trace/api/span/DatadogSpanBuilder.kt

@@ -25,6 +25,7 @@ interface DatadogSpanBuilder {
 
     /**
      * Specifies the origin of the span.
+     * The origin provides metadata about the context or source where the span was created.
      *
      * @param origin The origin string to associate with the span. Can be nullable.
      * @return The current instance of [DatadogSpanBuilder] to allow method chaining.
@@ -33,6 +34,8 @@ interface DatadogSpanBuilder {
 
     /**
      * Adds a tag to the span with the specified key and a nullable double value.
+     * Tags are used to add contextual information to spans, which can later be
+     * used for filtering, grouping, or analyzing spans in trace data.
      *
      * @param key The key identifying the tag. Cannot be null.
      * @param value The value associated with the tag. Can be null.
@@ -42,6 +45,8 @@ interface DatadogSpanBuilder {
 
     /**
      * Adds a tag to the span with the specified key and a nullable long value.
+     * Tags are used to add contextual information to spans, which can later be
+     * used for filtering, grouping, or analyzing spans in trace data.
      *
      * @param key The key identifying the tag. Must not be null.
      * @param value The nullable long value associated with the tag.
@@ -51,6 +56,8 @@ interface DatadogSpanBuilder {
 
     /**
      * Adds a tag to the span with the specified key and a nullable value of any type.
+     * Tags are used to add contextual information to spans, which can later be
+     * used for filtering, grouping, or analyzing spans in trace data.
      *
      * @param key The key identifying the tag. Cannot be null.
      * @param value The nullable value associated with the tag.
@@ -59,23 +66,24 @@ interface DatadogSpanBuilder {
     fun withTag(key: String, value: Any?): DatadogSpanBuilder
 
     /**
-     * Specifies the resource name of the span.
+     * Specifies the resource name of the span.The resource name is used to describe
+     * the operation or endpoint associated with the span.
      *
      * @param resourceName The resource name to associate with the span.
      * @return The current instance of [DatadogSpanBuilder] to allow method chaining.
      */
     fun withResourceName(resourceName: String?): DatadogSpanBuilder
 
     /**
-     * Sets the parent context for the span being built.
+     * Sets the parent context for the span being built. Allowing to link related operations together.
      *
      * @param parentContext The parent context to associate with the span. Can be null.
      * @return The current instance of [DatadogSpanBuilder] to enable method chaining.
      */
     fun withParentContext(parentContext: DatadogSpanContext?): DatadogSpanBuilder
 
     /**
-     * Sets the parent span for the span being built. Default implementation usually use parentSpan only for
+     * Sets the parent span for the span being built. The default implementation uses parentSpan only for
      * context retrieval.
      *
      * @param parentSpan The parent span to associate with the span being built. Can be null.