= improve doc & javadoc

README-EN.md

@@ -221,18 +221,18 @@ At present, `TTL` agent has decorated below `JDK` execution components(aka. thre
     - decoration implementation code is in [`TtlTimerTaskTransformlet.java`](src/main/java/com/alibaba/ttl/threadpool/agent/internal/transformlet/impl/TtlTimerTaskTransformlet.java), supports since version **_`2.7.0`_**.
     - **_NOTE_**: Since version `2.11.2` decoration for `TimerTask` default is enable (because correctness is first concern, not the best practice like "It is not recommended to use `TimerTask`" :); before version `2.11.1` default is disable.
     - enabled/disable by agent argument `ttl.agent.enable.timer.task`:
-        - `-javaagent:path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:true`
-        - `-javaagent:path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:false`
+        - `-javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:true`
+        - `-javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:false`
     - more info about `TTL` agent arguments, see [the javadoc of `TtlAgent.java`](src/main/java/com/alibaba/ttl/threadpool/agent/TtlAgent.java).
 
 Add start options on Java command:
 
-- `-javaagent:path/to/transmittable-thread-local-2.x.x.jar`
+- `-javaagent:path/to/transmittable-thread-local-2.x.y.jar`
 
 **NOTE**：
 
 - Because TTL agent modified the `JDK` std lib classes, make code refer from std lib class to the TTL classes, so the TTL Agent jar must be added to `boot classpath`.
-- Since `v2.6.0`, TTL agent jar will auto add self to `boot classpath`. But you **should _NOT_** modify the downloaded TTL jar file name in the maven repo(eg: `transmittable-thread-local-2.x.x.jar`).
+- Since `v2.6.0`, TTL agent jar will auto add self to `boot classpath`. But you **should _NOT_** modify the downloaded TTL jar file name in the maven repo(eg: `transmittable-thread-local-2.x.y.jar`).
     - if you modified the downloaded TTL jar file name(eg: `ttl-foo-name-changed.jar`),
         you must add TTL agent jar to `boot classpath` manually by java option `-Xbootclasspath/a:path/to/ttl-foo-name-changed.jar`.
 
@@ -252,7 +252,7 @@ More info:
 Java command example:
 
 ```bash
-java -javaagent:transmittable-thread-local-2.x.x.jar \
+java -javaagent:transmittable-thread-local-2.x.y.jar \
     -cp classes \
     com.alibaba.demo.ttl.agent.AgentDemo
 ```

README.md

@@ -248,8 +248,8 @@ Demo参见[`AgentDemo.kt`](src/test/java/com/alibaba/demo/ttl/agent/AgentDemo.kt
     - 修饰实现代码在[`TtlTimerTaskTransformlet.java`](src/main/java/com/alibaba/ttl/threadpool/agent/internal/transformlet/impl/TtlTimerTaskTransformlet.java)。从版本 **_`2.7.0`_** 开始支持。
     - **_注意_**：从`2.11.2`版本开始缺省开启`TimerTask`的修饰（因为保证正确性是第一位，而不是最佳实践『不推荐使用`TimerTask`』:）；`2.11.1`版本及其之前的版本没有缺省开启`TimerTask`的修饰。
     - 使用`Agent`参数`ttl.agent.enable.timer.task`开启/关闭`TimerTask`的修饰：
-        - `-javaagent:path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:true`
-        - `-javaagent:path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:false`
+        - `-javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:true`
+        - `-javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:false`
     - 更多关于`TTL Agent`参数的配置说明详见[`TtlAgent.java`的JavaDoc](src/main/java/com/alibaba/ttl/threadpool/agent/TtlAgent.java)。
 
 > **关于`java.util.TimerTask`/`java.util.Timer`**
@@ -265,7 +265,7 @@ Demo参见[`AgentDemo.kt`](src/test/java/com/alibaba/demo/ttl/agent/AgentDemo.kt
 因为修饰了`JDK`标准库的类，标准库由`bootstrap class loader`加载；修饰后的`JDK`类引用了`TTL`的代码，所以`Java Agent`使用方式下`TTL Jar`文件需要配置到`boot class path`上。
 
 `TTL`从`v2.6.0`开始，加载`TTL Agent`时会自动设置`TTL Jar`到`boot class path`上。  
-**_注意_**：不能修改从`Maven`库下载的`TTL Jar`文件名（形如`transmittable-thread-local-2.x.x.jar`）。
+**_注意_**：不能修改从`Maven`库下载的`TTL Jar`文件名（形如`transmittable-thread-local-2.x.y.jar`）。
 如果修改了，则需要自己手动通过`-Xbootclasspath JVM`参数来显式配置（就像`TTL`之前的版本的做法一样）。
 
 自动设置`TTL Jar`到`boot class path`的实现是通过指定`TTL Java Agent Jar`文件里`manifest`文件（`META-INF/MANIFEST.MF`）的`Boot-Class-Path`属性：
@@ -283,15 +283,15 @@ Demo参见[`AgentDemo.kt`](src/test/java/com/alibaba/demo/ttl/agent/AgentDemo.kt
 
 #### `Java`的启动参数配置
 
-在`Java`的启动参数加上：`-javaagent:path/to/transmittable-thread-local-2.x.x.jar`。
+在`Java`的启动参数加上：`-javaagent:path/to/transmittable-thread-local-2.x.y.jar`。
 
-如果修改了下载的`TTL`的`Jar`的文件名（`transmittable-thread-local-2.x.x.jar`），则需要自己手动通过`-Xbootclasspath JVM`参数来显式配置：  
+如果修改了下载的`TTL`的`Jar`的文件名（`transmittable-thread-local-2.x.y.jar`），则需要自己手动通过`-Xbootclasspath JVM`参数来显式配置：  
 比如修改文件名成`ttl-foo-name-changed.jar`，则还加上`Java`的启动参数：`-Xbootclasspath/a:path/to/ttl-foo-name-changed.jar`
 
 `Java`命令行示例如下：
 
 ```bash
-java -javaagent:path/to/transmittable-thread-local-2.x.x.jar \
+java -javaagent:path/to/transmittable-thread-local-2.x.y.jar \
     -cp classes \
     com.alibaba.demo.ttl.agent.AgentDemo
 ```

docs/release-action-list.md

@@ -9,22 +9,22 @@
             - `./scripts/gen-pom4ide.sh` 重新生成 `pom4ide`
         - 更新`README`
             - 更新badge的引用，由master分支名改成Tag名  
-                - `sed 's/master/v2.x.x/g' -i README*`
+                - `sed 's/master/v2.x.y/g' -i README*`
                 - `javadoc` badge的JavaDoc链接到固定版本  
-                    https://alibaba.github.io/transmittable-thread-local/apidocs/2.x.x/index.html
+                    https://alibaba.github.io/transmittable-thread-local/apidocs/2.x.y/index.html
             - 示例`Maven`依赖的版本
             - 更新`JavaDoc`链接到固定版本
-2. 新建并Push Tag，如`v2.x.x`  
-    - `git tag -m 'release v2.x.x' v2.x.x`
-    - `git push origin v2.x.x`
+2. 新建并Push Tag，如`v2.x.y`  
+    - `git tag -m 'release v2.x.y' v2.x.y`
+    - `git push origin v2.x.y`
 3. 等待Tag的CI通过 <https://travis-ci.org/alibaba/transmittable-thread-local/builds>
 3. 执行`scripts/checke-japi-compliance.sh`，检查`API`兼容性
 4. 发布版本到`Maven`中央库  
     `./mvnw clean && ./mvnw deploy -DperformRelease`
 5. 更新`JavaDoc`
     1. 生成`JavaDoc`，更新到分支`gh-pages`
         - `git checkout gh-pages`
-        - `mv target/apidocs apidocs/2.x.x`
+        - `mv target/apidocs apidocs/2.x.y`
     2. 修改`index.html`<http://alibaba.github.io/transmittable-thread-local/apidocs>的重定向到最新版本的`JavaDoc`
 6. 编写Release Note： <https://github.com/alibaba/transmittable-thread-local/releases>
 7. 升级`Master`分支的开发版本号

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

@@ -13,7 +13,7 @@
 import java.util.logging.Logger;
 
 /**
- * {@link TransmittableThreadLocal} can transmit value from the thread of submitting task to the thread of executing task.
+ * {@link TransmittableThreadLocal}({@code TTL}) can transmit value from the thread of submitting task to the thread of executing task.
  * <p>
  * <b>Note</b>:<br>
  * {@link TransmittableThreadLocal} extends {@link InheritableThreadLocal},

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

@@ -41,11 +41,11 @@ public final class TtlExecutors {
      * transmit the {@link TransmittableThreadLocal} from the task submit time of {@link Runnable}
      * to the execution time of {@link Runnable}.
      * <p>
-     * NOTE: sine v2.12.0 the idempotency of return wrapper Executor is changed to true,
-     * so the wrapper Executor can be cooperation the usage of "Decorate Runnable and Callable".
+     * NOTE: sine v2.12.0 the idempotency of return wrapped Executor is changed to true,
+     * so the wrapped Executor can be cooperated with the usage of "Decorate Runnable and Callable".
      * <p>
-     * about idempotency: if is idempotent,
-     * allowed submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapper Executor;
+     * About idempotency: if is idempotent,
+     * it's allowed to submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapped Executor;
      * otherwise throw {@link IllegalStateException}.
      *
      * @param executor input Executor
@@ -66,11 +66,11 @@ public static Executor getTtlExecutor(@Nullable Executor executor) {
      * transmit the {@link TransmittableThreadLocal} from the task submit time of {@link Runnable} or {@link java.util.concurrent.Callable}
      * to the execution time of {@link Runnable} or {@link java.util.concurrent.Callable}.
      * <p>
-     * NOTE: sine v2.12.0 the idempotency of return wrapper ExecutorService is changed to true,
-     * so the wrapper ExecutorService can be cooperation the usage of "Decorate Runnable and Callable".
+     * NOTE: sine v2.12.0 the idempotency of return wrapped ExecutorService is changed to true,
+     * so the wrapped ExecutorService can be cooperated with the usage of "Decorate Runnable and Callable".
      * <p>
-     * about idempotency: if is idempotent,
-     * allowed submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapper ExecutorService;
+     * About idempotency: if is idempotent,
+     * it's allowed to submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapped ExecutorService;
      * otherwise throw {@link IllegalStateException}.
      *
      * @param executorService input ExecutorService
@@ -92,11 +92,11 @@ public static ExecutorService getTtlExecutorService(@Nullable ExecutorService ex
      * transmit the {@link TransmittableThreadLocal} from the task submit time of {@link Runnable} or {@link java.util.concurrent.Callable}
      * to the execution time of {@link Runnable} or {@link java.util.concurrent.Callable}.
      * <p>
-     * NOTE: sine v2.12.0 the idempotency of return wrapper ScheduledExecutorService is changed to true,
-     * so the wrapper ScheduledExecutorService can be cooperation the usage of "Decorate Runnable and Callable".
+     * NOTE: sine v2.12.0 the idempotency of return wrapped ScheduledExecutorService is changed to true,
+     * so the wrapped ScheduledExecutorService can be cooperated with the usage of "Decorate Runnable and Callable".
      * <p>
-     * about idempotency:if is idempotent,
-     * allowed submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapper scheduledExecutorService;
+     * About idempotency: if is idempotent,
+     * it's allowed to submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapped ScheduledExecutorService;
      * otherwise throw {@link IllegalStateException}.
      *
      * @param scheduledExecutorService input scheduledExecutorService
@@ -113,7 +113,7 @@ public static ScheduledExecutorService getTtlScheduledExecutorService(@Nullable
     }
 
     /**
-     * check the executor is TTL wrapper executor or not.
+     * check the executor is a TTL executor wrapper or not.
      * <p>
      * if the parameter executor is TTL wrapper, return {@code true}, otherwise {@code false}.
      * <p>
@@ -132,7 +132,7 @@ public static <T extends Executor> boolean isTtlWrapper(@Nullable T executor) {
     }
 
     /**
-     * Unwrap TTL wrapper executor to the original/underneath one.
+     * Unwrap TTL executor wrapper to the original/underneath one.
      * <p>
      * if the parameter executor is TTL wrapper, return the original/underneath executor;
      * otherwise, just return the input parameter executor.
@@ -157,7 +157,7 @@ public static <T extends Executor> T unwrap(@Nullable T executor) {
     }
 
     /**
-     * Wrapper of  {@link ThreadFactory}, disable inheritable.
+     * Wrapper of {@link ThreadFactory}, disable inheritable.
      *
      * @param threadFactory input thread factory
      * @see DisableInheritableThreadFactory

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

@@ -43,7 +43,7 @@
  * More info about "disable inheritable" see {@link com.alibaba.ttl.TransmittableThreadLocal}.
  * <p>
  * Configuration example:<br>
- * {@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.disable.inheritable.for.thread.pool:true}
+ * {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.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}.
@@ -58,8 +58,8 @@
  * <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>
+ * <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar}</li>
+ * <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.logger:STDOUT}</li>
  * </ul>
  *
  * <h3>Enable/disable TimerTask class decoration</h3>
@@ -72,16 +72,16 @@
  * <p>
  * Configuration example:
  * <ul>
- * <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:false}</li>
- * <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:true}</li>
+ * <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:false}</li>
+ * <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:true}</li>
  * </ul>
  *
  * <h3>Multi key configuration example</h3>
- * {@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.logger:STDOUT,ttl.agent.disable.inheritable.for.thread.pool:true}
+ * {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.logger:STDOUT,ttl.agent.disable.inheritable.for.thread.pool:true}
  *
  * <h2>About boot classpath for TTL agent</h2>
  * <b><i>NOTE:</i></b> 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>
+ * 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.y.jar}).<br>
  * if you modified the downloaded TTL agent jar file name(eg: {@code ttl-foo-name-changed.jar}),
  * you must add TTL agent jar to {@code boot classpath} manually
  * by java option {@code -Xbootclasspath/a:path/to/ttl-foo-name-changed.jar}.