Move javadoc for ContextManager.clearAll.

Signed-off-by: Sjoerd Talsma <[email protected]>

context-propagation-api/src/main/java/nl/talsmasoftware/context/api/Context.java

@@ -46,6 +46,8 @@
  */
 public interface Context<T> extends Closeable {
 
+    // TODO think about removing Context.getValue as ContextManager.getActiveContextValue() should suffice.
+
     /**
      * The value associated with this context.
      *

context-propagation-api/src/main/java/nl/talsmasoftware/context/api/ContextManager.java

@@ -68,6 +68,27 @@ public interface ContextManager<T> {
      */
     void clear();
 
+    /**
+     * Clears all active contexts from the current thread.
+     *
+     * <p>
+     * Contexts that are 'stacked' (i.e. restore the previous state upon close)
+     * should be closed in a way that includes all 'parent' contexts as well.
+     *
+     * <p>
+     * This operation is not intended to be used by general application code
+     * as it likely breaks any 'stacked' active context that surrounding code may depend upon.
+     *
+     * <p>
+     * Appropriate use includes thread management, where threads are reused by some pooling mechanism.<br>
+     * For example, it is considered safe to clear the context when obtaining a 'fresh' thread from a
+     * thread pool (as no context expectations should exist at that point).<br>
+     * An even better strategy would be to clear the context right before returning a used thread
+     * back to the pool as this will allow any unclosed contexts to be garbage collected.<br>
+     * Besides preventing contextual issues, this reduces the risk of memory leaks by unbalanced context calls.
+     *
+     * @since 2.0.0
+     */
     static void clearAll() {
         ContextSnapshotImpl.clearActiveContexts();
     }