improve javadoc

src/main/java/com/alibaba/ttl/TransmittableThreadLocal.java

@@ -161,13 +161,37 @@ public class TransmittableThreadLocal<T> extends InheritableThreadLocal<T> {
     }
 
     /**
-     * {@link Transmitter} is <b><i>internal</i></b> manipulation api of {@link TransmittableThreadLocal},
-     * expose internal {@link #capture()}/{@link #replay(Object)}/{@link #restore(Object)} operation
-     * of {@link TransmittableThreadLocal} values for middleware integration,
-     * like {@link TtlRunnable} and {@link TtlCallable}.
+     * {@link Transmitter} transmit all {@link TransmittableThreadLocal} of current thread to
+     * any other thread by static method {@link #capture()} =&gt; {@link #replay(Object)} =&gt; {@link #restore(Object)} (aka {@code CRR} operation).
      * <p>
-     * {@link Transmitter} can transmit all {@link TransmittableThreadLocal} of current thread to
-     * any other thread by {@link #capture()} =&gt; {@link #replay(Object)} =&gt; {@link #restore(Object)}.
+     * {@link Transmitter} is <b><i>internal</i></b> manipulation api for <b><i>framework/middleware integration</i></b>;
+     * In general, you will <b><i>never</i></b> use it in the <i>biz/application code</i>!
+     * <p>
+     * Below is the example:
+     *
+     * <pre><code>
+     * ///////////////////////////////////////////////////////////////////////////
+     * // in thread 1, capture all TransmittableThreadLocal values of thread 1
+     * ///////////////////////////////////////////////////////////////////////////
+     *
+     * Object captured = Transmitter.capture();
+     *
+     * ///////////////////////////////////////////////////////////////////////////
+     * // in thread 2
+     * ///////////////////////////////////////////////////////////////////////////
+     *
+     * // replay all TransmittableThreadLocal values from thread 1
+     * Object backup = Transmitter.replay(captured);
+     * try {
+     *     // your biz logic, run with the TransmittableThreadLocal values of thread 1
+     *     ...
+     * } finally {
+     *     // restore the TransmittableThreadLocal of thread 2 when replay
+     *     Transmitter.restore(backup);
+     * }
+     * </code></pre>
+     * <p>
+     * see the implementation code of {@link TtlRunnable} and {@link TtlCallable} for more actual code sample.
      *
      * @author Yang Fang (snoop dot fy at gmail dot com)
      * @see TtlRunnable
@@ -178,7 +202,7 @@ public class TransmittableThreadLocal<T> extends InheritableThreadLocal<T> {
         /**
          * Capture all {@link TransmittableThreadLocal} values in current thread.
          *
-         * @return captured {@link TransmittableThreadLocal}
+         * @return the captured {@link TransmittableThreadLocal} values
          */
         public static Object capture() {
             Map<TransmittableThreadLocal<?>, Object> captured = new HashMap<>();
@@ -189,11 +213,11 @@ public class TransmittableThreadLocal<T> extends InheritableThreadLocal<T> {
         }
 
         /**
-         * Replay the captured {@link TransmittableThreadLocal} values by {@link #capture()}
-         * after backup {@link TransmittableThreadLocal} values in current thread.
+         * Replay the captured {@link TransmittableThreadLocal} values from {@link #capture()},
+         * and return the backup {@link TransmittableThreadLocal} values in current thread before replay.
          *
-         * @param captured captured {@link TransmittableThreadLocal} values from other thread by {@link #capture()}
-         * @return backup {@link TransmittableThreadLocal} values before replay
+         * @param captured captured {@link TransmittableThreadLocal} values from other thread from {@link #capture()}
+         * @return the backup {@link TransmittableThreadLocal} values before replay
          * @see #capture()
          */
         public static Object replay(Object captured) {
@@ -231,9 +255,9 @@ public class TransmittableThreadLocal<T> extends InheritableThreadLocal<T> {
         }
 
         /**
-         * Restore {@link TransmittableThreadLocal} values backup from {@link Transmitter#replay(Object)}.
+         * Restore the backup {@link TransmittableThreadLocal} values from {@link Transmitter#replay(Object)}.
          *
-         * @param backup the {@link TransmittableThreadLocal} values backup from {@link Transmitter#replay(Object)}
+         * @param backup the backup {@link TransmittableThreadLocal} values from {@link Transmitter#replay(Object)}
          */
         public static void restore(Object backup) {
             @SuppressWarnings("unchecked")

src/main/java/com/alibaba/ttl/TtlCallable.java

@@ -18,6 +18,7 @@ import static com.alibaba.ttl.TransmittableThreadLocal.Transmitter.restore;
  * Use factory method {@link #get(Callable)} to get decorated instance.
  *
  * @author Jerry Lee (oldratlee at gmail dot com)
+ * @see com.alibaba.ttl.threadpool.TtlExecutors
  * @see java.util.concurrent.Executor
  * @see java.util.concurrent.ExecutorService
  * @see java.util.concurrent.ThreadPoolExecutor

src/main/java/com/alibaba/ttl/TtlRunnable.java

@@ -17,6 +17,7 @@ import static com.alibaba.ttl.TransmittableThreadLocal.Transmitter.restore;
  * Use factory methods {@link #get} / {@link #gets} to create instance.
  *
  * @author Jerry Lee (oldratlee at gmail dot com)
+ * @see com.alibaba.ttl.threadpool.TtlExecutors
  * @see java.util.concurrent.Executor
  * @see java.util.concurrent.ExecutorService
  * @see java.util.concurrent.ThreadPoolExecutor

src/main/java/com/alibaba/ttl/package-info.java

@@ -2,5 +2,8 @@
  * TTL API.
  *
  * @author Jerry Lee (oldratlee at gmail dot com)
+ * @see com.alibaba.ttl.TransmittableThreadLocal
+ * @see com.alibaba.ttl.TtlRunnable
+ * @see com.alibaba.ttl.TtlCallable
  */
 package com.alibaba.ttl;

src/main/java/com/alibaba/ttl/threadpool/TtlExecutors.java

@@ -11,6 +11,13 @@ import java.util.concurrent.ScheduledExecutorService;
  *
  * @author Jerry Lee (oldratlee at gmail dot com)
  * @since 0.9.0
+ * @see java.util.concurrent.Executor
+ * @see java.util.concurrent.ExecutorService
+ * @see java.util.concurrent.ThreadPoolExecutor
+ * @see java.util.concurrent.ScheduledThreadPoolExecutor
+ * @see java.util.concurrent.Executors
+ * @see java.util.concurrent.CompletionService
+ * @see java.util.concurrent.ExecutorCompletionService
  */
 public final class TtlExecutors {
     /**

src/main/java/com/alibaba/ttl/threadpool/agent/TtlTransformer.java

@@ -23,6 +23,11 @@ import javassist.NotFoundException;
 /**
  * @author Jerry Lee (oldratlee at gmail dot com)
  * @since 0.9.0
+ * @see java.util.concurrent.Executor
+ * @see java.util.concurrent.ExecutorService
+ * @see java.util.concurrent.ThreadPoolExecutor
+ * @see java.util.concurrent.ScheduledThreadPoolExecutor
+ * @see java.util.concurrent.Executors
  */
 public class TtlTransformer implements ClassFileTransformer {
     private static final Logger logger = Logger.getLogger(TtlTransformer.class.getName());