Add package javadoc for API module.

This fixes #591

Signed-off-by: Sjoerd Talsma <sjoerdtalsma@users.noreply.github.com>

Author: sjoerdtalsma

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

@@ -45,7 +45,8 @@ public interface Context extends Closeable {
      * <p>
      * It is the responsibility of the one activating a new context to also close it <em>from the same thread</em>.
      *
-     * @implSpec It <strong>must</strong> be possible to call the {@linkplain #close()} method multiple times. Later calls must have no effect and should not throw exceptions.
+     * @implSpec It <strong>must</strong> be possible to call the {@linkplain #close()} method multiple times.
+     * Later calls must have no effect and should not throw exceptions.
      * @implNote Implementors are advised to <em>restore</em> the previous thread-local value upon close, but are not obliged to do so.
      */
     void close();

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

@@ -19,30 +19,34 @@
  * Manages a {@linkplain Context} by providing a standard way of interacting with {@linkplain ThreadLocal} values.
  *
  * <p>
+ * Thread-local values can be accessed via a ContextManager by:
+ *
+ * <p>
  * {@linkplain ThreadLocal} values can be accessed via a ContextManager by:
  * <ul>
+ *     <li>Calling {@linkplain #getActiveContextValue()} which <em>gets</em> the current thread-local value.
  *     <li>Calling {@linkplain #activate(Object)} which <em>sets</em> the given value until {@linkplain Context#close()}
- *     is called on the resulting {@linkplain Context}.
- *     <li>Calling {@linkplain #getActiveContextValue()} which <em>sets</em> the current thread-local value.
+ *     is called on the returned {@linkplain Context}.
  *     <li>Calling {@linkplain #clear()} which <em>removes</em> the thread-local value.
  * </ul>
  *
- * <p>
- * Implementations must be made available through the {@linkplain java.util.ServiceLoader ServiceLoader}.<br>
- * For details how to make your implementation available, please see the documentation of {@link java.util.ServiceLoader}.
- *
  * @param <T> type of the context value
  * @author Sjoerd Talsma
+ * @implSpec Implementations <strong>must</strong> be made available through Java's ServiceLoader.
+ * For details how to make your implementation available, please see the documentation of {@link java.util.ServiceLoader}.
  * @since 2.0.0
  */
 public interface ContextManager<T> {
-
     /**
      * Activate a new context containing the specified <code>value</code>.
      *
      * <p>
      * Whether the value is allowed to be <code>null</code> is up to the implementation.
      *
+     * <p>
+     * The specified value is the <em>active</em> value for the current thread,
+     * until the returned {@linkplain Context} is closed, or another value gets activated.
+     *
      * @param value The value to activate a new context for.
      * @return The new <em>active</em> context containing the specified value
      * which should be closed by the caller at the end of its lifecycle from the same thread.
@@ -58,16 +62,15 @@ public interface ContextManager<T> {
     T getActiveContextValue();
 
     /**
-     * Clears the current context and any potential parent contexts that exist.
+     * Clears the current context and any potential parent contexts that exist, for the current thread.
      *
      * <p>
      * This is an optional operation.<br>
      * When all active contexts are initialized in combination with try-with-resources blocks,
      * it is not necessary to call clear.
      *
      * <p>
-     * The operation exists to allow thread pool management making sure
-     * to clear all contexts before returning threads to the pool.
+     * The operation exists to allow thread-pool management to clear all contexts before returning threads to the pool.
      *
      * <p>
      * This method normally should only get called by {@linkplain #clearAll()}.

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

@@ -19,14 +19,11 @@
 import java.util.concurrent.Callable;
 
 /**
- * Snapshot capturing all active values from detected {@link ContextManager} implementations.
+ * Captures active values from all detected {@linkplain ContextManager} implementations.
  *
  * <p>
- * Such a snapshot can be passed to another thread,
- * allowing all captured values to be reactivated in that other thread by a single method call.
- *
- * <p>
- * A context snapshot can be obtained from the {@linkplain #capture()} method.
+ * A context snapshot can be obtained from the {@linkplain #capture()} method.<br>
+ * The captured values in this snapshot can be reactivated in another thread.
  *
  * <p>
  * <strong>Important:</strong> Make sure to <strong>always</strong> call {@link Reactivation#close()}

context-propagation-api/src/main/java/nl/talsmasoftware/context/api/package-info.java

@@ -14,37 +14,41 @@
  * limitations under the License.
  */
 /**
- * API concepts used throughout the {@code context-propagation} library.
+ * The API of the {@code context-propagation} library.
+ *
+ * <h2>{@linkplain nl.talsmasoftware.context.api.ContextSnapshot}</h2>
+ * <p>
+ * Captures active values from all detected {@linkplain nl.talsmasoftware.context.api.ContextManager} implementations.
+ *
+ * <p>
+ * The captured values in a snapshot can be reactivated in another thread.<br>
+ * Snapshot reactivations must be closed again to avoid leaking context.
  *
- * <h2>{@linkplain nl.talsmasoftware.context.api.Context}</h2>
  * <p>
- * A {@linkplain nl.talsmasoftware.context.api.Context context} contains a value.<br>
- * There can be one active context per thread. A context remains active until it is closed or another context
- * is activated in the same thread. Normally, a context is backed by a {@linkplain java.lang.ThreadLocal ThreadLocal}
- * variable.
+ * All context aware utility classes in this library are tested
+ * to make sure they reactivate and close snapshots in a safe way.
  *
  * <h2>{@linkplain nl.talsmasoftware.context.api.ContextManager}</h2>
  * <p>
- * Manages the active context.
- * Can {@linkplain nl.talsmasoftware.context.api.ContextManager#activate(java.lang.Object) activate a new context}
- * and provides access to
- * the {@linkplain nl.talsmasoftware.context.api.ContextManager#getActiveContextValue() active context value}.
+ * Manages {@linkplain nl.talsmasoftware.context.api.Context contexts} by providing a standard way of interacting
+ * with {@linkplain java.lang.ThreadLocal} values.
  *
  * <p>
- * For normal application code it should not be necessary to interact with context managers directly.
- * Instead, using the various context-aware utility classes from the core module will automatically propagate
- * any supported context types to background threads for you.
+ * Managed context values can be accessed via a ContextManager by:
+ * <ul>
+ *  <li>Calling {@code getActiveContextValue()} which <em>gets</em> the current thread-local value.
+ *  <li>Calling {@code activate(value)} which <em>sets</em> the given value until {@code close()}
+ *  is called on the returned {@code Context}.
+ *  <li>Calling {@code clear()} which <em>removes</em> the thread-local value.
+ * </ul>
  *
- * <h2>{@linkplain nl.talsmasoftware.context.api.ContextSnapshot}</h2>
+ * <h2>{@linkplain nl.talsmasoftware.context.api.Context}</h2>
  * <p>
- * A snapshot contains the active context value from all known context managers.<br>
- * These values can be reactivated all together in another thread
- * by {@linkplain nl.talsmasoftware.context.api.ContextSnapshot#reactivate() reactivating} the snapshot.<br>
- * Reactivated snapshots <strong>must</strong> be closed to avoid leaking context.
+ * Abstraction for an activated {@linkplain java.lang.ThreadLocal} value.
  *
  * <p>
- * All context aware utility classes in this the core module of this library are tested
- * to make sure they reactivate and close snapshots in a safe way.
+ * When the context manager {@code activates} a value, a new Context is returned.
+ * Closing this context will remove the activated value again.
  *
  * @author Sjoerd Talsma
  */

readme.md

@@ -36,7 +36,7 @@ to make sure they reactivate _and_ close snapshots in a safe way.
 
 Manages a [context](#context) by providing a standard way of interacting with `ThreadLocal` values.
 
-Thread-local values can be accessed via a ContextManager by:
+Managed thread-local values can be accessed via a ContextManager by:
 
 - Calling `getActiveContextValue()` which _gets_ the current thread-local value.
 - Calling `activate(value)` which _sets_ the given value until `close()` is called on the resulting `Context`.