improve javadoc

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

@@ -13,28 +13,38 @@ import java.util.logging.Logger;
  * <p>
  * <b>Note</b>:<br>
  * {@link TransmittableThreadLocal} extends {@link java.lang.InheritableThreadLocal},
- * so {@link TransmittableThreadLocal} first is a {@link java.lang.InheritableThreadLocal}.
+ * so {@link TransmittableThreadLocal} first is a {@link java.lang.InheritableThreadLocal}.<br>
  * If the <b>inheritable</b> ability of {@link InheritableThreadLocal} has <b>potential leaking problem</b>,
- * you can disable the <b>Inheritable</b> ability
+ * you can disable the <b>inheritable</b> ability:
  * <p>
- * 1) by overriding method {@link #childValue(Object)}:
- * <pre> {@code
- *   TransmittableThreadLocal<String> transmittableThreadLocal = new TransmittableThreadLocal<String>() {
- *       protected String childValue(String parentValue) {
- *           return initialValue();
- *       }
- *   }}</pre>
+ * ❶ by wrapping thread factory using method {@link com.alibaba.ttl.threadpool.TtlExecutors#getDisableInheritableThreadFactory(java.util.concurrent.ThreadFactory)} / {@link com.alibaba.ttl.threadpool.TtlForkJoinPoolHelper#getDefaultDisableInheritableForkJoinWorkerThreadFactory()}
+ * for thread pooling components({@link java.util.concurrent.ThreadPoolExecutor}, {@link java.util.concurrent.ForkJoinPool}).
+ * Inheritable feature in thread pooling components should <b>never</b> happen,
+ * because threads in thread pooling components is pre-created and pooled, these threads is neutral for biz logic/data.
+ * <br>
+ * You can turn on "disable inheritable for thread pool" by {@link com.alibaba.ttl.threadpool.agent.TtlAgent}
+ * so as to wrap thread factory for thread pooling components({@link java.util.concurrent.ThreadPoolExecutor}, {@link java.util.concurrent.ForkJoinPool})
+ * automatically and transparently.
  * <p>
- * 2) or by {@link com.alibaba.ttl.threadpool.DisableInheritableThreadFactory}, {@link com.alibaba.ttl.threadpool.DisableInheritableForkJoinWorkerThreadFactory}
+ * ❷ or by overriding method {@link #childValue(Object)}.
+ * Whether the value should be inheritable or not can be controlled by the data owner,
+ * disable it <b>carefully</b> when data owner have a clear idea.
+ * <pre> {@code TransmittableThreadLocal<String> transmittableThreadLocal = new TransmittableThreadLocal<String>() {
+ *     protected String childValue(String parentValue) {
+ *         return initialValue();
+ *     }
+ * }}</pre>
+ * <p>
+ * More discussion about "disable the <b>inheritable</b> ability"
+ * see <a href="https://github.com/alibaba/transmittable-thread-local/issues/100">
+ *     issue #100: disable Inheritable when it's not necessary and buggy(eg. has potential memory leaking problem)</a>.
  *
  * @author Jerry Lee (oldratlee at gmail dot com)
  * @author Yang Fang (snoop dot fy at gmail dot com)
  * @see TtlRunnable
  * @see TtlCallable
- * @see com.alibaba.ttl.threadpool.DisableInheritableThreadFactory
  * @see com.alibaba.ttl.threadpool.TtlExecutors#getDisableInheritableThreadFactory(java.util.concurrent.ThreadFactory)
  * @see com.alibaba.ttl.threadpool.TtlExecutors#getDefaultDisableInheritableThreadFactory()
- * @see com.alibaba.ttl.threadpool.DisableInheritableForkJoinWorkerThreadFactory
  * @see com.alibaba.ttl.threadpool.TtlForkJoinPoolHelper#getDisableInheritableForkJoinWorkerThreadFactory(java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory)
  * @see com.alibaba.ttl.threadpool.TtlForkJoinPoolHelper#getDefaultDisableInheritableForkJoinWorkerThreadFactory()
  * @since 0.10.0

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

@@ -20,6 +20,8 @@ import java.util.logging.Level;
 /**
  * TTL Java Agent.
  * <p>
+ * The configuration/arguments for agent see the javadoc of {@link #premain(String, Instrumentation)}
+ * <p>
  * <b><i>NOTE:</i></b><br>
  * Since {@code v2.6.0}, TTL agent jar will auto add self to {@code boot classpath}.
  * But you <b>should <i>NOT</i></b> modify the downloaded TTL jar file name in the maven repo(eg: {@code transmittable-thread-local-2.x.x.jar}).<br>
@@ -56,27 +58,10 @@ public final class TtlAgent {
      * <h2>TTL Agent configuration</h2>
      * Configure TTL agent via agent arguments, format is {@code k1:v1,k2:v2}. Below is available configuration keys.
      *
-     * <h3>The log configuration</h3>
-     * The log of TTL Java Agent is config by key {@code ttl.agent.logger}.
-     *
-     * <ul>
-     * <li>{@code ttl.agent.logger : STDERR}<br>
-     * only log to {@code stderr} when error.
-     * This is <b>default</b>, when no/unrecognized configuration for key {@code ttl.agent.logger}.</li>
-     * <li>{@code ttl.agent.logger : STDOUT}<br>
-     * Log to {@code stdout}, more info than {@code ttl.agent.logger:STDERR}; This is needed when developing.</li>
-     * </ul>
-     * <p>
-     * configuration example:
-     * <ul>
-     * <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar}</li>
-     * <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.logger:STDOUT}</li>
-     * </ul>
-     *
      * <h3>Disable inheritable for thread pool</h3>
      * <p>
      * Enable "disable inheritable" for thread pool, config by key {@code ttl.agent.disable.inheritable.for.thread.pool}.
-     * When no configuration for this key, default does <b>not</b> enabled.
+     * When no configuration for this key, default does <b>not</b> enabled. Since version {@code 2.10.1}.
      *
      * <ul>
      * <li>rewrite the {@link java.util.concurrent.ThreadFactory} constructor parameter
@@ -94,9 +79,26 @@ public final class TtlAgent {
      * Configuration example:<br>
      * {@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.disable.inheritable.for.thread.pool:true}
      *
+     * <h3>The log configuration</h3>
+     * The log of TTL Java Agent is config by key {@code ttl.agent.logger}. Since version {@code 2.6.0}.
+     *
+     * <ul>
+     * <li>{@code ttl.agent.logger : STDERR}<br>
+     * only log to {@code stderr} when error.
+     * This is <b>default</b>, when no/unrecognized configuration for key {@code ttl.agent.logger}.</li>
+     * <li>{@code ttl.agent.logger : STDOUT}<br>
+     * Log to {@code stdout}, more info than {@code ttl.agent.logger:STDERR}; This is needed when developing.</li>
+     * </ul>
+     * <p>
+     * configuration example:
+     * <ul>
+     * <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar}</li>
+     * <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.logger:STDOUT}</li>
+     * </ul>
+     *
      * <h3>Enable TimerTask class decoration</h3>
      * Enable TimerTask class decoration is config by key {@code ttl.agent.enable.timer.task}.
-     * When no configuration for this key, default does <b>not</b> enabled.
+     * When no configuration for this key, default does <b>not</b> enabled. Since version {@code 2.7.0}.
      * <p>
      * Configuration example:<br>
      * {@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:true}