javadoc

components/context/src/main/java/datadog/context/Context.java

@@ -5,10 +5,20 @@
 
 import javax.annotation.Nullable;
 
-/** Immutable context scoped to an execution unit or carrier object. */
+/**
+ * Immutable context scoped to an execution unit or carrier object.
+ *
+ * <p>Each element of the context is accessible by its {@link ContextKey}. Keys represents product
+ * or functional areas and should be created sparingly. Elements in the context may themselves be
+ * mutable.
+ */
 public interface Context {
 
-  /** Returns the root context. */
+  /**
+   * Returns the root context.
+   *
+   * <p>This is the initial local context that all contexts extend.
+   */
   static Context root() {
     return manager().root();
   }
@@ -72,14 +82,14 @@ static Context detachFrom(Object carrier) {
   <T> T get(ContextKey<T> key);
 
   /**
-   * Creates a new context with the given key-value mapping.
+   * Creates a new context from the same elements, except the key is now mapped to the given value.
    *
    * @return New context with the key-value mapping.
    */
   <T> Context with(ContextKey<T> key, T value);
 
   /**
-   * Creates a new context with a value that has its own implicit key.
+   * Creates a new context from the same elements, except the implicit key is mapped to this value.
    *
    * @return New context with the implicitly keyed value.
    */

components/context/src/main/java/datadog/context/ContextKey.java

@@ -3,7 +3,7 @@
 import java.util.concurrent.atomic.AtomicInteger;
 
 /**
- * Key for indexing values of type {@link T} stored in a {@link Context}.
+ * {@link Context} key that maps to a value of type {@link T}.
  *
  * <p>Keys are compared by identity rather than by name. Each stored context type should either
  * share its key for re-use or implement {@link ImplicitContextKeyed} to keep its key private.

components/context/src/main/java/datadog/context/ContextManager.java

@@ -3,7 +3,11 @@
 /** Manages context across execution units. */
 public interface ContextManager {
 
-  /** Returns the root context. */
+  /**
+   * Returns the root context.
+   *
+   * <p>This is the initial local context that all contexts extend.
+   */
   Context root();
 
   /**