Rename context(ContextMap) to setContextMap(ContextMap) and fix some doc strings

Author: bryce-anderson

servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/AsyncContextProvider.java

@@ -48,12 +48,14 @@ interface AsyncContextProvider {
     ContextMap context();
 
     /**
-     * Set the {@link ContextMap}.
+     * Set the async context {@link ContextMap}.
+     *
+     * Note that unlike {@link AsyncContextProvider#attachContextMap(ContextMap)}, this method does not provide a
+     * {@link Scope} to restore the state to what it was previously.
      *
      * @param context the new value for {@link ContextMap}.
-     * @return {@code this}.
      */
-    void context(ContextMap context);
+    void setContextMap(ContextMap context);
 
     /**
      * Attach the {@link ContextMap} to the current local scope.

servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/CopyOnWriteContextMap.java

@@ -194,15 +194,18 @@ public ContextMap captured() {
         return this;
     }
 
+    // CapturedContext method. For the base async context implementation, attaching means setting the correct
+    // AsyncContextProvider thread-local to _this_ ContextMap instance.
     @Override
     public Scope attachContext() {
         return AsyncContext.provider().attachContextMap(this);
     }
 
-    // Scope method
+    // Scope method. For the base async context implementation, the `prev` map instance is returned as the Scope if that
+    // is the context state that needs to be restored and restoring just means setting it to the thread-local.
     @Override
     public void close() {
-        AsyncContext.provider().context(this);
+        AsyncContext.provider().setContextMap(this);
     }
 
     private interface CopyContextMap {

servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/DefaultAsyncContextProvider.java

@@ -65,7 +65,7 @@ public final ContextMap context() {
     }
 
     @Override
-    public final void context(ContextMap contextMap) {
+    public final void setContextMap(ContextMap contextMap) {
         final Thread currentThread = Thread.currentThread();
         if (currentThread instanceof ContextMapHolder) {
             final ContextMapHolder asyncContextMapHolder = (ContextMapHolder) currentThread;

servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/NoopAsyncContextProvider.java

@@ -57,7 +57,7 @@ public CapturedContext captureContext(ContextMap contextMap) {
     }
 
     @Override
-    public void context(@Nullable ContextMap contextMap) {
+    public void setContextMap(@Nullable ContextMap contextMap) {
         // noop
     }
 

servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/Scope.java

@@ -15,15 +15,12 @@
  */
 package io.servicetalk.concurrent.api;
 
-import io.servicetalk.context.api.ContextMap;
-
 /**
  * An abstraction for detaching a context from the current thread.
  *
  * This abstraction is intended to allow the modifications performed by
- * {@link AsyncContextProvider#attachContextMap(ContextMap)} to be undone. In practice, this may look like restoring
- * a {@link ThreadLocal} to the state it had before the call to
- * {@link AsyncContextProvider#attachContextMap(ContextMap)}.
+ * {@link CapturedContext#attachContext()} to be undone. In practice, this may look like restoring a {@link ThreadLocal}
+ * to the state it had before the call to {@link CapturedContext#attachContext()}.
  */
 interface Scope extends AutoCloseable {