优化注释

jetlinks · Dec 30, 2021 · 2b183e1 · 2b183e1
1 parent 05fe74b
commit 2b183e1
Show file tree

Hide file tree

Showing 18 changed files with 347 additions and 22 deletions.
diff --git a/src/main/java/org/jetlinks/core/Value.java b/src/main/java/org/jetlinks/core/Value.java
@@ -2,36 +2,91 @@
 
 import java.util.Date;
 
+/**
+ * 用于包装各种数据
+ *
+ * @author zhouhao
+ * @see Values
+ * @since 1.0
+ */
 public interface Value {
+    /**
+     * 转为String
+     *
+     * @return String的值
+     * @see String#valueOf(int)
+     */
     default String asString() {
         return String.valueOf(get());
     }
 
+    /**
+     * 转为Int
+     *
+     * @return Int值
+     */
     default int asInt() {
         return as(Integer.class);
     }
 
+    /**
+     * 转为Long
+     *
+     * @return Long值
+     */
     default long asLong() {
         return as(Long.class);
     }
 
+    /**
+     * 转为Boolean
+     *
+     * @return Boolean值
+     */
     default boolean asBoolean() {
         return Boolean.TRUE.equals(get())
                 || "true".equals(get());
     }
 
+    /**
+     * 转为Number,由具体的值决定实际的Number类型
+     *
+     * @return Number
+     */
     default Number asNumber() {
         return as(Number.class);
     }
 
+    /**
+     * 转为Date类型
+     *
+     * @return Date
+     */
     default Date asDate() {
         return as(Date.class);
     }
 
+    /**
+     * 获取原始值
+     *
+     * @return 原始值
+     */
     Object get();
 
+    /**
+     * 尝试转为指定的类型.可能会抛出{@link  ClassCastException}
+     *
+     * @param type 类型
+     * @param <T>  类型
+     * @return 指定类型的值
+     */
     <T> T as(Class<T> type);
 
+    /**
+     * 包装一个简单的值
+     * @param value 原始值
+     * @return 值
+     */
     static Value simple(Object value) {
         return SimpleValue.of(value);
     }

diff --git a/src/main/java/org/jetlinks/core/Values.java b/src/main/java/org/jetlinks/core/Values.java
@@ -54,10 +54,20 @@ public interface Values {
      */
     Set<String> getNonExistentKeys(Collection<String> keys);
 
+    /**
+     * 是否为空
+     *
+     * @return true 为空，false 非空
+     */
     default boolean isEmpty() {
         return size() == 0;
     }
 
+    /**
+     * 是否不为空
+     *
+     * @return true 不为空，false 为空
+     */
     default boolean isNoEmpty() {
         return size() > 0;
     }

diff --git a/src/main/java/org/jetlinks/core/cache/Caches.java b/src/main/java/org/jetlinks/core/cache/Caches.java
@@ -8,6 +8,22 @@
 import java.util.concurrent.ConcurrentMap;
 import java.util.function.Supplier;
 
+/**
+ * 缓存工具,根据环境来创建不同的ConcurrentMap实现,
+ * <p>
+ * 支持 jctools{@link NonBlockingHashMap },Caffeine{@link Caffeine},Guava.
+ *
+ * 优先级:
+ * <ul style="list-style-type:decimal;">
+ *     <li>jctools</li>
+ *     <li>Caffeine</li>
+ *     <li>Guava</li>
+ * </ul>
+ *
+ * @author zhouhao
+ * @see ConcurrentMap
+ * @since 1.1.5
+ */
 public class Caches {
 
     private static final Supplier<ConcurrentMap<Object, Object>> cacheSupplier;

diff --git a/src/main/java/org/jetlinks/core/cache/SPIFileQueueBuilder.java b/src/main/java/org/jetlinks/core/cache/SPIFileQueueBuilder.java
@@ -9,6 +9,21 @@
 import java.util.Map;
 import java.util.ServiceLoader;
 
+/**
+ * 可拓展的{@link FileQueue.Builder}实现,利用jdk spi功能进行自定义拓展:
+ *
+ * <pre>
+ *     --resources
+ *     ---|---META-INF
+ *     ---|-----|--services
+ *     ---|-----|-----|---org.jetlinks.core.cache.FileQueueBuilderFactory
+ * </pre>
+ *
+ * @param <T> Queue元素类型
+ * @see FileQueueBuilderFactory
+ * @see FileQueue.Builder
+ * @since 1.1.7
+ */
 @Slf4j
 class SPIFileQueueBuilder<T> implements FileQueue.Builder<T> {
 

diff --git a/src/main/java/org/jetlinks/core/cluster/ClusterCounter.java b/src/main/java/org/jetlinks/core/cluster/ClusterCounter.java
@@ -2,6 +2,12 @@
 
 import reactor.core.publisher.Mono;
 
+/**
+ * 集群计数器支持
+ *
+ * @author zhouhao
+ * @since 1.1.4
+ */
 public interface ClusterCounter {
 
     /**

diff --git a/src/main/java/org/jetlinks/core/cluster/ClusterSet.java b/src/main/java/org/jetlinks/core/cluster/ClusterSet.java
@@ -5,16 +5,52 @@
 
 import java.util.Collection;
 
+/**
+ * 集群Set支持
+ *
+ * @param <T> 元素类型
+ * @author zhouhao
+ * @since 1.1.3
+ */
 public interface ClusterSet<T> {
 
+    /**
+     * 添加数据到Set中
+     *
+     * @param value 数据
+     * @return true 成功 false 失败
+     */
     Mono<Boolean> add(T value);
 
+    /**
+     * 添加多个数据到Set中
+     *
+     * @param values 数据集
+     * @return true 成功 false 失败
+     */
     Mono<Boolean> add(Collection<T> values);
 
+    /**
+     * 从Set中删除数据
+     *
+     * @param value 要删除到数据
+     * @return true 成功 false 失败
+     */
     Mono<Boolean> remove(T value);
 
+    /**
+     * 从Set中删除多个数据
+     *
+     * @param values 要删除到数据集
+     * @return true 成功 false 失败
+     */
     Mono<Boolean> remove(Collection<T> values);
 
+    /**
+     * 获取Set中到全部数据
+     *
+     * @return 数据流
+     */
     Flux<T> values();
 
 }
diff --git a/src/main/java/org/jetlinks/core/codec/Decoder.java b/src/main/java/org/jetlinks/core/codec/Decoder.java
@@ -3,7 +3,6 @@
 import org.jetlinks.core.Payload;
 
 import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
 
 public interface Decoder<T> {
 

diff --git a/src/main/java/org/jetlinks/core/config/ConfigKey.java b/src/main/java/org/jetlinks/core/config/ConfigKey.java
@@ -1,29 +1,78 @@
 package org.jetlinks.core.config;
 
+/**
+ * 用于定义配置key,增加key的可读性
+ *
+ * @param <V> 值类型
+ * @author zhouhao
+ * @since 1.0
+ */
 public interface ConfigKey<V> {
+    /**
+     * @return key
+     */
     String getKey();
 
+    /**
+     * key的名称,说明
+     *
+     * @return name
+     */
     default String getName() {
         return getKey();
     }
 
+    /**
+     * key 对应值的类型
+     *
+     * @return 类型
+     */
     default Class<V> getType() {
         return (Class<V>) Object.class;
     }
 
+    /**
+     * 根据一个字符串来创建一个ConfigKey,它的key和name的值都为此字符串
+     *
+     * @param key 字符串
+     * @param <T> 值类型
+     * @return ConfigKey
+     */
     static <T> ConfigKey<T> of(String key) {
         return of(key, key);
     }
 
+    /**
+     * 指定key和名称创建key
+     *
+     * @param key  key
+     * @param name 名称
+     * @param <T>  值类型
+     * @return ConfigKey
+     */
     static <T> ConfigKey<T> of(String key, String name) {
         return SimpleConfigKey.of(key, name, (Class<T>) Object.class);
     }
 
+    /**
+     * 指定key字符串和名称以及值类型创建key
+     *
+     * @param key  key
+     * @param name 名称
+     * @param <T>  值类型
+     * @param type 类型
+     * @return ConfigKey
+     */
     static <T> ConfigKey<T> of(String key, String name, Class<T> type) {
         return SimpleConfigKey.of(key, name, type);
     }
 
-
+    /**
+     * 使用指定的值，将key转为ConfigKeyValue
+     *
+     * @param value 值
+     * @return ConfigKeyValue
+     */
     default ConfigKeyValue<V> value(V value) {
         return new ConfigKeyValue<V>() {
             @Override

diff --git a/src/main/java/org/jetlinks/core/config/ConfigKeyValue.java b/src/main/java/org/jetlinks/core/config/ConfigKeyValue.java
@@ -1,12 +1,35 @@
 package org.jetlinks.core.config;
 
+/**
+ * 配置键值对
+ *
+ * @param <V> 值类型
+ * @author zhouhao
+ * @since 1.0
+ */
 public interface ConfigKeyValue<V> extends ConfigKey<V> {
+
+    /**
+     * 获取值
+     *
+     * @return 值
+     */
     V getValue();
 
+    /**
+     * 判断值是否为null
+     *
+     * @return true 表示为null,false 表示不为null
+     */
     default boolean isNull() {
         return null == getValue();
     }
 
+    /**
+     * 判断值是否不为null
+     *
+     * @return true 表示不为null,false 表示为null
+     */
     default boolean isNotNull() {
         return null != getValue();
     }