Update documents

backend/codegen/src/main/kotlin/net/mamoe/mirai/console/codegen/ValueSettingCodegen.kt

@@ -29,7 +29,7 @@ internal object ValueSettingCodegen {
             appendKCode(
                 """
                     /**
-                     * Represents a non-null [$ktType] value.
+                     * 表示一个不可空 [$ktType] [Value].
                      */
                     public interface ${ktType}Value : PrimitiveValue<$ktType>
                 """

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/setting/Setting.kt

@@ -180,6 +180,14 @@ public inline fun <reified T> Setting.value(default: T): SerializerAwareValue<T>
 
 /**
  * 通过具体化类型创建一个 [SerializerAwareValue].
+ * @see valueFromKType 查看更多实现信息
+ */
+@LowPriorityInOverloadResolution
+public inline fun <reified T> Setting.value(): SerializerAwareValue<T> =
+    value(T::class.run { objectInstance ?: createInstanceSmart() } as T)
+
+/**
+ * 通过一个特定的 [KType] 创建 [Value], 并设置初始值.
  *
  * 对于 [List], [Map], [Set] 等标准库类型, 这个函数会尝试构造 [LinkedHashMap] 等相关类型.
  * 而对于自定义数据类型, 本函数只会反射获取 [objectInstance][KClass.objectInstance] 或使用无参构造器构造实例.
@@ -190,13 +198,6 @@ public inline fun <reified T> Setting.value(default: T): SerializerAwareValue<T>
  * - 标准库数据类型 ([Map.Entry], [Pair], [Triple])
  * - 和使用 [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization) 的 [Serializable] 标记的
  */
-@LowPriorityInOverloadResolution
-public inline fun <reified T> Setting.value(): SerializerAwareValue<T> =
-    value(T::class.run { objectInstance ?: createInstanceSmart() } as T)
-
-/**
- * Creates a [Value] with specified [KType], and set default value.
- */
 @Suppress("UNCHECKED_CAST")
 @ConsoleExperimentalAPI
 public fun <T> Setting.valueFromKType(type: KType, default: T): SerializerAwareValue<T> =

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/setting/Value.kt

@@ -20,21 +20,21 @@ import net.mamoe.mirai.console.util.ConsoleExperimentalAPI
 import kotlin.reflect.KProperty
 
 /**
- * Represents a observable, immutable value wrapping.
+ * 表示一个可被观测的, 不可变的值包装.
  *
- * The value can be modified by delegation just like Kotlin's `var`, however it can also be done by the user, e.g. changing using the UI frontend.
+ * [Value.value] 可以像 Kotlin 的 `var` 一样被修改, 然而它也可能被用户修改, 如通过 UI 前端.
  *
- * Some frequently used types are specially treated with performance enhancement by codegen.
+ * 一些常用的基础类型实现由代码生成创建特性的优化.
  *
- * @see PrimitiveValue
+ * @see PrimitiveValue 基础数据类型实现
- * @see CompositeValue
+ * @see CompositeValue 复合数据类型实现
  */
 public interface Value<T> {
     public var value: T
 }
 
 /**
- * Typically returned by [Setting.value] functions.
+ * 可被序列化的 [Value].
  */
 public class SerializableValue<T>(
     private val delegate: Value<T>,
@@ -66,59 +66,74 @@ public class SerializableValue<T>(
  * @see Setting.value 创建一个这样的 [SerializerAwareValue]
  */
 public interface SerializerAwareValue<T> : Value<T> {
+    /**
+     * 用于更新 [value] 的序列化器. 在反序列化时不会创建新的 [T] 对象实例.
+     *
+     * - 序列化: `val text: String = Yaml.default.encodeToString(serializer, Unit)`
+     * - 反序列化 (本质上是更新 [value], 不创建新的 [T] 实例): `Yaml.default.decodeFromString(serializer, text)`
+     */
     public val serializer: KSerializer<Unit>
 
     public companion object {
+        /**
+         * 使用 [指定格式格式][format] 序列化一个 [SerializerAwareValue]
+         */
         @JvmStatic
-        @ConsoleExperimentalAPI("will be changed due to reconstruction of kotlinx.serialization")
         public fun <T> SerializerAwareValue<T>.serialize(format: StringFormat): String {
             return format.encodeToString(this.serializer, Unit)
         }
 
+        /**
+         * 使用 [指定格式格式][format] 序列化一个 [SerializerAwareValue]
+         */
         @JvmStatic
-        @ConsoleExperimentalAPI("will be changed due to reconstruction of kotlinx.serialization")
         public fun <T> SerializerAwareValue<T>.serialize(format: BinaryFormat): ByteArray {
             return format.encodeToByteArray(this.serializer, Unit)
         }
 
+        /**
+         * 使用 [指定格式格式][format] 反序列化 (更新) 一个 [SerializerAwareValue]
+         */
         @JvmStatic
-        @ConsoleExperimentalAPI("will be changed due to reconstruction of kotlinx.serialization")
+        public fun <T> SerializerAwareValue<T>.deserialize(format: StringFormat, string: String) {
-        public fun <T> SerializerAwareValue<T>.deserialize(format: StringFormat, value: String) {
+            format.decodeFromString(this.serializer, string)
-            format.decodeFromString(this.serializer, value)
         }
 
+        /**
+         * 使用 [指定格式格式][format] 反序列化 (更新) 一个 [SerializerAwareValue]
+         */
         @JvmStatic
-        @ConsoleExperimentalAPI("will be changed due to reconstruction of kotlinx.serialization")
+        public fun <T> SerializerAwareValue<T>.deserialize(format: BinaryFormat, bytes: ByteArray) {
-        public fun <T> SerializerAwareValue<T>.deserialize(format: BinaryFormat, value: ByteArray) {
+            format.decodeFromByteArray(this.serializer, bytes)
-            format.decodeFromByteArray(this.serializer, value)
         }
     }
 }
 
+/**
+ * 用于支持属性委托
+ */
 @JvmSynthetic
 public inline operator fun <T> Value<T>.getValue(mySetting: Any?, property: KProperty<*>): T = value
 
+/**
+ * 用于支持属性委托
+ */
 @JvmSynthetic
 public inline operator fun <T> Value<T>.setValue(mySetting: Any?, property: KProperty<*>, value: T) {
     this.value = value
 }
 
 /**
- * The serializer for a specific kind of [Value].
+ * 基础数据类型 [Value]
- */
-public typealias ValueSerializer<T> = KSerializer<Value<T>>
-
-/**
- * Represents a observable *primitive* value wrapping.
  *
- * 9 types that are considered *primitive*:
+ * 9 个被认为是 *基础类型* 的类型:
- * - Integers: [Byte], [Short], [Int], [Long]
+ * - 整数: [Byte], [Short], [Int], [Long]
- * - Floating: [Float], [Double]
+ * - 浮点: [Float], [Double]
  * - [Boolean]
  * - [Char], [String]
  *
- * Note: The values are actually *boxed* because of the generic type T.
+ * 注意: 目前这些类型都会被装箱, 由于泛型 T. 在将来可能会有优化处理.
- * *Primitive* indicates only it is one of the 9 types mentioned above.
+ * *Primitive* 仅表示一个类型是上面 9 种类型之一.
  */
 public interface PrimitiveValue<T> : Value<T>
 
@@ -126,71 +141,77 @@ public interface PrimitiveValue<T> : Value<T>
 //// region PrimitiveValues CODEGEN ////
 
 /**
- * Represents a non-null [Byte] value.
+ * 表示一个不可空 [Byte] [Value].
  */
 public interface ByteValue : PrimitiveValue<Byte>
 
 /**
- * Represents a non-null [Short] value.
+ * 表示一个不可空 [Short] [Value].
  */
 public interface ShortValue : PrimitiveValue<Short>
 
 /**
- * Represents a non-null [Int] value.
+ * 表示一个不可空 [Int] [Value].
  */
 public interface IntValue : PrimitiveValue<Int>
 
 /**
- * Represents a non-null [Long] value.
+ * 表示一个不可空 [Long] [Value].
  */
 public interface LongValue : PrimitiveValue<Long>
 
 /**
- * Represents a non-null [Float] value.
+ * 表示一个不可空 [Float] [Value].
  */
 public interface FloatValue : PrimitiveValue<Float>
 
 /**
- * Represents a non-null [Double] value.
+ * 表示一个不可空 [Double] [Value].
  */
 public interface DoubleValue : PrimitiveValue<Double>
 
 /**
- * Represents a non-null [Char] value.
+ * 表示一个不可空 [Char] [Value].
  */
 public interface CharValue : PrimitiveValue<Char>
 
 /**
- * Represents a non-null [Boolean] value.
+ * 表示一个不可空 [Boolean] [Value].
  */
 public interface BooleanValue : PrimitiveValue<Boolean>
 
 /**
- * Represents a non-null [String] value.
+ * 表示一个不可空 [String] [Value].
  */
 public interface StringValue : PrimitiveValue<String>
 
 //// endregion PrimitiveValues CODEGEN ////
 
 
+/**
+ * 复合数据类型实现
+ */
 @ConsoleExperimentalAPI
 public interface CompositeValue<T> : Value<T>
 
 
 /**
- * Superclass of [CompositeListValue], [PrimitiveListValue].
+ * @see [CompositeListValue]
+ * @see [PrimitiveListValue]
  */
 public interface ListValue<E> : CompositeValue<List<E>>
 
 /**
- * Elements can by anything, wrapped as [Value].
+ * 复合数据类型的 [List]
- * @param E is not primitive types.
+ *
+ * @param E 不是基础数据类型
  */
 public interface CompositeListValue<E> : ListValue<E>
 
 /**
- * Elements can only be primitives, not wrapped.
+ * 针对基础类型优化的 [List]
- * @param E is not primitive types.
+ *
+ * @param E 是基础类型
  */
 public interface PrimitiveListValue<E> : ListValue<E>
 
@@ -205,19 +226,20 @@ public interface PrimitiveLongListValue : PrimitiveListValue<Long>
 
 
 /**
- * Superclass of [CompositeSetValue], [PrimitiveSetValue].
+ * @see [CompositeSetValue]
+ * @see [PrimitiveSetValue]
  */
 public interface SetValue<E> : CompositeValue<Set<E>>
 
 /**
- * Elements can by anything, wrapped as [Value].
+ * 复合数据类型 [Set]
- * @param E is not primitive types.
+ * @param E 是基础数据类型
  */
 public interface CompositeSetValue<E> : SetValue<E>
 
 /**
- * Elements can only be primitives, not wrapped.
+ * 基础数据类型 [Set]
- * @param E is not primitive types.
+ * @param E 是基础数据类型
  */
 public interface PrimitiveSetValue<E> : SetValue<E>
 
@@ -232,7 +254,8 @@ public interface PrimitiveLongSetValue : PrimitiveSetValue<Long>
 
 
 /**
- * Superclass of [CompositeMapValue], [PrimitiveMapValue].
+ * @see [CompositeMapValue]
+ * @see [PrimitiveMapValue]
  */
 public interface MapValue<K, V> : CompositeValue<Map<K, V>>