docs: improve javadoc of TtlWrapper/TtlWrappers 📚

alibaba · Dec 16, 2023 · cbc0f64 · cbc0f64
1 parent cd17648
commit cbc0f64
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 20 deletions.
diff --git a/ttl-core/src/main/java/com/alibaba/ttl3/TtlWrappers.java b/ttl-core/src/main/java/com/alibaba/ttl3/TtlWrappers.java
@@ -2,15 +2,13 @@
 
 import com.alibaba.crr.composite.Backup;
 import com.alibaba.crr.composite.Capture;
-import com.alibaba.ttl3.executor.TtlExecutors;
 import com.alibaba.ttl3.spi.TtlEnhanced;
 import com.alibaba.ttl3.spi.TtlWrapper;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 import org.jetbrains.annotations.Contract;
 
-import java.util.concurrent.Callable;
 import java.util.function.*;
 
 import static com.alibaba.ttl3.transmitter.Transmitter.*;
@@ -30,15 +28,18 @@
  * <ul>
  * <li>all methods is {@code null}-safe, when input parameter is {@code null}, return {@code null}.</li>
  * <li>all wrap method skip wrapping (aka. just return input parameter), when input parameter is already wrapped.</li>
- * <li>the wrap methods for {@link Runnable} and {@link java.util.concurrent.Callable} are provided
- *     by {@link TtlRunnable#get(Runnable)} and {@link TtlCallable#get(Callable)}.</li>
+ * <li>the wrap methods for {@link Runnable} and {@link java.util.concurrent.Callable Callable} are provided
+ *     by {@link TtlRunnable#get(Runnable)} and {@link TtlCallable#get(java.util.concurrent.Callable) TtlCallable.get(Callable)}.</li>
+ * <li>the wrap methods for {@link java.util.concurrent.Executor Executor} are provided
+ *     by {@link com.alibaba.ttl3.executor.TtlExecutors TtlExecutors}.</li>
  * </ul>
  *
  * @author Jerry Lee (oldratlee at gmail dot com)
  * @author huangfei1101 (fei.hf at alibaba-inc dot com)
  * @see TtlRunnable
  * @see TtlCallable
  * @see TtlWrapper
+ * @see com.alibaba.ttl3.executor.TtlExecutors TtlExecutors
  */
 public final class TtlWrappers {
     /**
@@ -122,17 +123,23 @@ public static <T, U, R> BiFunction<T, U, R> wrapBiFunction(@Nullable BiFunction<
      * this method is {@code null}-safe, when input parameter is {@code null}, return {@code null};
      * if input parameter is not a {@link TtlWrapper} just return input.
      *
-     * @see TtlRunnable#unwrap(Runnable)
-     * @see TtlCallable#unwrap(java.util.concurrent.Callable)
-     * @see TtlExecutors#unwrapTtlExecutor(java.util.concurrent.Executor)
-     * @see TtlExecutors#unwrapDisableInheritableThreadFactory(java.util.concurrent.ThreadFactory)
-     * @see TtlExecutors#unwrapDisableInheritableForkJoinWorkerThreadFactory(java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory)
-     * @see TtlExecutors#unwrapTtlRunnableUnwrapComparator(java.util.Comparator)
      * @see TtlWrappers#wrapSupplier(Supplier)
      * @see TtlWrappers#wrapConsumer(Consumer)
      * @see TtlWrappers#wrapBiConsumer(BiConsumer)
      * @see TtlWrappers#wrapFunction(Function)
      * @see TtlWrappers#wrapBiFunction(BiFunction)
+     * @see TtlRunnable#get(Runnable)
+     * @see TtlCallable#get(java.util.concurrent.Callable) TtlCallable.get(Callable)
+     * @see com.alibaba.ttl3.executor.TtlExecutors#getTtlExecutor(java.util.concurrent.Executor) TtlExecutors.getTtlExecutor(Executor)
+     * @see com.alibaba.ttl3.executor.TtlExecutors#getTtlExecutorService(java.util.concurrent.ExecutorService) TtlExecutors.getTtlExecutorService(ExecutorService)
+     * @see com.alibaba.ttl3.executor.TtlExecutors#getDisableInheritableThreadFactory(java.util.concurrent.ThreadFactory) TtlExecutors.getDisableInheritableThreadFactory(ThreadFactory)
+     * @see com.alibaba.ttl3.executor.TtlExecutors#getDisableInheritableForkJoinWorkerThreadFactory(java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory) TtlExecutors.getDisableInheritableForkJoinWorkerThreadFactory(ForkJoinWorkerThreadFactory)
+     * @see TtlRunnable#unwrap(Runnable)
+     * @see TtlCallable#unwrap(java.util.concurrent.Callable) TtlCallable.unwrap(Callable)
+     * @see com.alibaba.ttl3.executor.TtlExecutors#unwrapTtlExecutor(java.util.concurrent.Executor) TtlExecutors.unwrapTtlExecutor(Executor)
+     * @see com.alibaba.ttl3.executor.TtlExecutors#unwrapDisableInheritableThreadFactory(java.util.concurrent.ThreadFactory) TtlExecutors.unwrapDisableInheritableThreadFactory(ThreadFactory)
+     * @see com.alibaba.ttl3.executor.TtlExecutors#unwrapDisableInheritableForkJoinWorkerThreadFactory(java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory) TtlExecutors.unwrapDisableInheritableForkJoinWorkerThreadFactory(ForkJoinWorkerThreadFactory)
+     * @see com.alibaba.ttl3.executor.TtlExecutors#unwrapTtlRunnableUnwrapComparator(java.util.Comparator) TtlExecutors.unwrapTtlRunnableUnwrapComparator(Comparator)
      * @see #isWrapper(Object)
      */
     @Nullable

diff --git a/ttl-core/src/main/java/com/alibaba/ttl3/spi/TtlWrapper.java b/ttl-core/src/main/java/com/alibaba/ttl3/spi/TtlWrapper.java
@@ -1,33 +1,35 @@
 package com.alibaba.ttl3.spi;
 
-import com.alibaba.ttl3.executor.TtlExecutors;
 import edu.umd.cs.findbugs.annotations.NonNull;
 
-import java.util.concurrent.ExecutorService;
-
 /**
  * Ttl Wrapper interface.
  * <p>
  * Used to mark wrapper types, for example:
  * <ul>
- *     <li>{@link com.alibaba.ttl3.TtlCallable TtlCallable}
- *     <li>{@code TtlExecutors} created by util method
- *         {@link TtlExecutors#getTtlExecutorService(ExecutorService)} getTtlExecutorService}
- *     <li>{@code DisableInheritableThreadFactory} created by util method
- *         {@link TtlExecutors#getDisableInheritableThreadFactory(java.util.concurrent.ThreadFactory) getDisableInheritableThreadFactory}
+ *     <li>{@link com.alibaba.ttl3.TtlRunnable TtlRunnable}s, {@link com.alibaba.ttl3.TtlCallable TtlCallable}s
+ *     <li>{@code TtlWrappers} created by util methods {@code wrap*()} of class
+ *         {@link com.alibaba.ttl3.TtlWrappers TtlWrappers},
+ *         e.g. {@link com.alibaba.ttl3.TtlWrappers#wrapSupplier(java.util.function.Supplier) wrapSupplier}
+ *     <li>{@code TtlExecutors} created by util methods {@code get*()} of class
+ *         {@link com.alibaba.ttl3.executor.TtlExecutors TtlExecutors},
+ *         e.g. {@link com.alibaba.ttl3.executor.TtlExecutors#getTtlExecutorService(java.util.concurrent.ExecutorService) getTtlExecutorService}
+ *     <li>{@code DisableInheritableThreadFactories} created by util method
+ *         {@link com.alibaba.ttl3.executor.TtlExecutors#getDisableInheritableThreadFactory(java.util.concurrent.ThreadFactory) getDisableInheritableThreadFactory}
  * </ul>
  *
  * @author Jerry Lee (oldratlee at gmail dot com)
  * @see com.alibaba.ttl3.TtlWrappers#unwrap
- * @see com.alibaba.ttl3.TtlCallable
  * @see com.alibaba.ttl3.TtlRunnable
+ * @see com.alibaba.ttl3.TtlCallable
+ * @see com.alibaba.ttl3.TtlWrappers
  * @see com.alibaba.ttl3.executor.TtlExecutors
  */
 public interface TtlWrapper<T> extends TtlEnhanced {
     /**
      * unwrap {@link TtlWrapper} to the original/underneath one.
      *
-     * @see com.alibaba.ttl3.TtlWrappers#unwrap(Object)
+     * @see com.alibaba.ttl3.TtlWrappers#unwrap
      */
     @NonNull
     T unwrap();