From 6600ce37cfe7a598c986dad8a62c62594430e4db Mon Sep 17 00:00:00 2001
From: Sjoerd Talsma <sjoerdtalsma@users.noreply.github.com>
Date: Fri, 29 Nov 2024 17:23:19 +0100
Subject: [PATCH] Move javadoc for ContextManager.clearAll.

Signed-off-by: Sjoerd Talsma <sjoerdtalsma@users.noreply.github.com>
---
 .../talsmasoftware/context/api/Context.java   |  2 ++
 .../context/api/ContextManager.java           | 21 +++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/context-propagation-api/src/main/java/nl/talsmasoftware/context/api/Context.java b/context-propagation-api/src/main/java/nl/talsmasoftware/context/api/Context.java
index 7b333a5b..8e3b70d5 100644
--- a/context-propagation-api/src/main/java/nl/talsmasoftware/context/api/Context.java
+++ b/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.
      *
diff --git a/context-propagation-api/src/main/java/nl/talsmasoftware/context/api/ContextManager.java b/context-propagation-api/src/main/java/nl/talsmasoftware/context/api/ContextManager.java
index 767ceb59..f5ed1368 100644
--- a/context-propagation-api/src/main/java/nl/talsmasoftware/context/api/ContextManager.java
+++ b/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();
     }