Improve opentracing javadocs.

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

managers/context-manager-opentelemetry/src/main/java/nl/talsmasoftware/context/managers/opentelemetry/package-info.java

@@ -14,24 +14,26 @@
  * limitations under the License.
  */
 /**
- * OpenTelemetry context propagation library.
+ * Manager to propagate {@linkplain io.opentelemetry.context.Context OpenTelemetry context}
+ * from one thread to another.
  *
  * <p>
- * Context Manager that delegates {@linkplain java.lang.ThreadLocal ThreadLocal} management to the
- * default {@linkplain io.opentelemetry.context.Context OpenTelemetry Context} storage.
+ * The ContextManager delegates {@linkplain java.lang.ThreadLocal ThreadLocal} management to the
+ * default {@linkplain io.opentelemetry.context.Context OpenTelemetry Context} storage.<br>
+ * <ul>
+ *     <li>Obtaining the current context value is delegated to
+ *     {@linkplain io.opentelemetry.context.Context#current()}.
+ *     <li>Intializing a new context value is delegated to
+ *     {@linkplain io.opentelemetry.context.Context#makeCurrent()}.
+ * </ul>
  *
  * <p>
- * Obtaining the current context value is delegated to
- * {@linkplain io.opentelemetry.context.Context#current()}.
- * Intializing a new context value is delegated to
- * {@linkplain io.opentelemetry.context.Context#makeCurrent()}.
- *
- * <p>
- * Adding the {@code context-manager-opentelemetry} jar to the classpath
+ * Adding the {@code context-manager-opentelemetry} library to the classpath
  * is all that is needed to include the {@link io.opentelemetry.context.Context OpenTelemetry Context}
  * in {@linkplain nl.talsmasoftware.context.api.ContextSnapshot ContextSnapshots}.
  * This propagates the context to other threads using the
  * {@code ContextAwareExecutorService} or {@code ContextAwareCompletableFuture}.
+ *
  * <p>
  * Also, any function <em>..WithContext</em> in the {@code nl.talsmasoftware.context.core.function} package
  * automatically activates the context snapshot around the function body.

managers/context-manager-opentracing/src/main/java/nl/talsmasoftware/context/managers/opentracing/ContextScopeManager.java

@@ -23,7 +23,7 @@
 import nl.talsmasoftware.context.core.threadlocal.AbstractThreadLocalContext;
 
 /**
- * Our own implementation of the opentracing {@linkplain ScopeManager}.
+ * A {@linkplain ThreadLocal} based {@linkplain ScopeManager} implementation.
  *
  * <p>
  * Manages opentracing {@linkplain Scope} and allows it to be nested within another active scope,
@@ -82,11 +82,22 @@ public static ContextScopeManager provider() {
     public ContextScopeManager() {
     }
 
+    /**
+     * Set the specified Span as the active instance for the current context (usually a thread).
+     *
+     * @param span the {@link Span} that should become the {@link #activeSpan()}
+     * @return The scope that <strong>must be</strong> closed in the same thread
+     */
     @Override
     public Scope activate(Span span) {
         return new ThreadLocalSpanContext(span);
     }
 
+    /**
+     * Return the currently active {@linkplain Span}.
+     *
+     * @return The active {@linkplain Span}, or {@code null} if none could be found.
+     */
     @Override
     public Span activeSpan() {
         return ThreadLocalSpanContext.currentSpan();
@@ -105,17 +116,27 @@ public Context<Span> initializeNewContext(Span value) {
         return (Context<Span>) activate(value);
     }
 
+    /**
+     * Returns the {@linkplain #activeSpan() active Span}.
+     *
+     * @return The active {@linkplain Span} or {@code null} if none could be found.
+     */
     @Override
     public Span getActiveContextValue() {
         return activeSpan();
     }
 
+    /**
+     * Clears <em>all</em> active spans from the current thread, including any parent contexts that may exist.
+     */
     @Override
     public void clear() {
         ThreadLocalSpanContext.remove();
     }
 
     /**
+     * String representation for this scope manager.
+     *
      * @return String representation for this context manager.
      */
     public String toString() {

managers/context-manager-opentracing/src/main/java/nl/talsmasoftware/context/managers/opentracing/SpanManager.java

@@ -24,10 +24,16 @@
 import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
- * Manager for <a href="http://opentracing.io/">OpenTracing</a> {@linkplain Span}.
+ * Manager to propagate {@linkplain Span OpenTracing span} from one thread to another.
  *
  * <p>
- * Management of {@linkplain Span spans} is delegated to the {@linkplain GlobalTracer}.
+ * Management of {@linkplain Span spans} is delegated to the configured {@linkplain GlobalTracer}.
+ * <ul>
+ *     <li>Obtaining the current context value is delegated to
+ *     {@linkplain io.opentracing.Tracer#activeSpan() active span}.
+ *     <li>Intializing a new context value is delegated to
+ *     {@linkplain GlobalTracer#activateSpan(Span)}.
+ * </ul>
  *
  * @author Sjoerd Talsma
  */
@@ -70,6 +76,9 @@ public Span getActiveContextValue() {
         return activeSpan();
     }
 
+    /**
+     * Does nothing, OpenTracing API does not support clearing the span.
+     */
     @Override
     public void clear() {
         // Opentracing API does not support clearing the span.
@@ -99,6 +108,12 @@ public Context<Span> initializeNewContext(final Span span) {
     }
 
     /**
+     * Returns a string representation of the object.
+     *
+     * <p>
+     * In this case, it is merely the simple class name as this span manager delegates to {@linkplain GlobalTracer}
+     * and therefore has no state or configuration to represent.
+     *
      * @return Simple class name as this class carries no internal state.
      */
     @Override

managers/context-manager-opentracing/src/main/java/nl/talsmasoftware/context/managers/opentracing/package-info.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2016-2024 Talsma ICT
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Manager to propagate {@linkplain io.opentracing.Span OpenTracing span} from one thread to another.
+ *
+ * <h2>{@linkplain nl.talsmasoftware.context.managers.opentracing.SpanManager}</h2>
+ * Management of {@linkplain io.opentracing.Span spans} is delegated by
+ * {@linkplain nl.talsmasoftware.context.managers.opentracing.SpanManager SpanManager} to the
+ * configured {@linkplain io.opentracing.util.GlobalTracer}.
+ * <ul>
+ *     <li>Obtaining the current context value is delegated to
+ *     {@linkplain io.opentracing.Tracer#activeSpan() active span}.
+ *     <li>Intializing a new context value is delegated to
+ *     {@linkplain io.opentracing.util.GlobalTracer#activateSpan(Span)}.
+ * </ul>
+ *
+ * <p>
+ * Adding the {@code context-manager-opentelemetry} library to the classpath will automatically
+ * include the {@linkplain io.opentracing.Span active Span}
+ * in {@linkplain nl.talsmasoftware.context.api.ContextSnapshot ContextSnapshots}.
+ * This propagates the context to other threads using the
+ * {@code ContextAwareExecutorService} or {@code ContextAwareCompletableFuture}.
+ *
+ * <p>
+ * Also, any function <em>..WithContext</em> in the {@code nl.talsmasoftware.context.core.function} package
+ * automatically activates the context snapshot around the function body.
+ *
+ * <h2>{@linkplain nl.talsmasoftware.context.managers.opentracing.ContextScopeManager}</h2>
+ * Our own ThreadLocal {@linkplain io.opentracing.ScopeManager} implementation.
+ *
+ * <p>
+ * Using it is optional. It will <strong>not</strong> be configured automatically.
+ * Check the configuration of your preferred tracer if it allows configuring a custom scope manager.
+ */
+package nl.talsmasoftware.context.managers.opentracing;
+
+import io.opentracing.Span;