From 3ded2cc87bca7a5ba6de5aaa8b08d41970ae8981 Mon Sep 17 00:00:00 2001
From: Him188 <Him188@mamoe.net>
Date: Sun, 13 Sep 2020 01:52:46 +0800
Subject: [PATCH] Add docs

---
 .../mamoe/mirai/console/data/PluginData.kt    |   4 +-
 .../mirai/console/data/PluginDataStorage.kt   |   2 +-
 .../mirai/console/extension/Extension.kt      |   4 +-
 .../mirai/console/permission/Permission.kt    |   2 +-
 .../mirai/console/permission/PermissionId.kt  |   3 +
 .../plugin/description/PluginDescription.kt   |   2 +-
 .../console/plugin/loader/PluginLoader.kt     |   4 +-
 docs/Extensions.md                            |  32 +++-
 docs/FrontEnd.md                              |  36 ++++-
 docs/PermissionService.md                     |   0
 docs/Permissions.md                           | 141 ++++++++++++++++++
 docs/PluginLoader.md                          |   0
 docs/Plugins.md                               |   2 +-
 docs/README.md                                |   2 -
 14 files changed, 219 insertions(+), 15 deletions(-)
 delete mode 100644 docs/PermissionService.md
 delete mode 100644 docs/PluginLoader.md

diff --git a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginData.kt b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginData.kt
index f76cc13a8..7288eaa3d 100644
--- a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginData.kt
+++ b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginData.kt
@@ -94,7 +94,7 @@ import kotlin.reflect.full.findAnnotation
  * newList.add(1) // 不会添加到 MyPluginData.nestedMap 中, 因为 `mutableListOf` 创建的 MutableList 被非引用地添加进了 MyPluginData.nestedMap
  * ```
  *
- * 一个解决方案是对 [SerializerAwareValue] 做映射或相关修改. 如 [PluginDataExtensions]。
+ * 一个解决方案是对 [SerializerAwareValue] 做映射或相关修改. 如 [PluginDataExtensions].
  *
  * 要查看详细的解释，请查看 [docs/PluginData.md](https://github.com/mamoe/mirai-console/blob/master/docs/PluginData.md)
  *
@@ -176,7 +176,7 @@ public interface PluginData {
     ): T
 
     /**
-     * 所有 [valueNodes] 更新和保存序列化器. 仅供内部使用。
+     * 所有 [valueNodes] 更新和保存序列化器. 仅供内部使用
      */
     public val updaterSerializer: KSerializer<Unit>
 
diff --git a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginDataStorage.kt b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginDataStorage.kt
index 0c9e0e55e..2f09d6f09 100644
--- a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginDataStorage.kt
+++ b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginDataStorage.kt
@@ -31,7 +31,7 @@ import java.nio.file.Path
  * [JvmPluginLoader] 实现一个 [PluginDataStorage], 用于管理所有 [JvmPlugin] 的 [PluginData] 实例.
  *
  * ### 实现 [PluginDataStorage]
- * 无特殊需求。实现两个成员函数即可。可参考内建 [MultiFilePluginDataStorageImpl]
+ * 无特殊需求. 实现两个成员函数即可. 可参考内建 [MultiFilePluginDataStorageImpl]
  *
  * @see PluginDataHolder
  * @see JvmPluginLoader.dataStorage
diff --git a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/Extension.kt b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/Extension.kt
index e26d1398a..744fbd719 100644
--- a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/Extension.kt
+++ b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/Extension.kt
@@ -20,10 +20,10 @@ import net.mamoe.mirai.console.plugin.jvm.JvmPlugin.Companion.onLoad
  * 表示一个扩展.
  *
  * ### 获取扩展
- * Console 不允许插件获取自己或其他插件注册的扩展。
+ * Console 不允许插件获取自己或其他插件注册的扩展
  *
  * ### 注册扩展
- * 插件仅能在 [JvmPlugin.onLoad] 阶段注册扩展。
+ * 插件仅能在 [JvmPlugin.onLoad] 阶段注册扩展
  *
  * ```kotlin
  * object MyPlugin : KotlinPlugin( /* ... */ ) {
diff --git a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/Permission.kt b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/Permission.kt
index 963863be7..289b4b214 100644
--- a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/Permission.kt
+++ b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/Permission.kt
@@ -76,7 +76,7 @@ public interface Permission {
 }
 
 /**
- * 根权限. 是所有权限的父权限.
+ * 根权限. 是所有权限的父权限. 权限 ID 为 "*:*"
  */
 @get:JvmSynthetic
 public val RootPermission: Permission
diff --git a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionId.kt b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionId.kt
index 8ec7a7f90..2d527d1e2 100644
--- a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionId.kt
+++ b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionId.kt
@@ -19,6 +19,9 @@ import net.mamoe.mirai.console.internal.data.map
  * 表示一个 [权限][Permission] 的唯一 ID.
  *
  * [PermissionId] 与 [Permission] 唯一对应.
+ *
+ * ### 字符串表示
+ * `"$namespace:$name"`. 如 "console:command.stop", "*:*"
  */
 @Serializable(with = PermissionId.PermissionIdAsStringSerializer::class)
 public data class PermissionId(
diff --git a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/description/PluginDescription.kt b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/description/PluginDescription.kt
index f0e2b4888..e9af5a3b1 100644
--- a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/description/PluginDescription.kt
+++ b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/description/PluginDescription.kt
@@ -49,7 +49,7 @@ public interface PluginDescription {
     public val id: String
 
     /**
-     * 插件名称用于展示给用户，仅取决于 `PluginDescription` 提供的 `name`，与主类类名等其他信息无关。
+     * 插件名称用于展示给用户，仅取决于 `PluginDescription` 提供的 `name`，与主类类名等其他信息无关.
      *
      * 名称允许中文, 允许各类符号，但不能完全是以下其中一种（忽略大小写）([FORBIDDEN_ID_NAMES]):
      * - console
diff --git a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/loader/PluginLoader.kt b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/loader/PluginLoader.kt
index dc68b75ec..04cae8515 100644
--- a/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/loader/PluginLoader.kt
+++ b/backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/loader/PluginLoader.kt
@@ -22,9 +22,9 @@ import net.mamoe.mirai.console.plugin.jvm.JvmPluginLoader
 /**
  * 插件加载器.
  *
- * 插件加载器只实现寻找插件列表, 加载插件, 启用插件, 关闭插件这四个功能。
+ * 插件加载器只实现寻找插件列表, 加载插件, 启用插件, 关闭插件这四个功能.
  *
- * 一个插件要在何时被加载，依赖如何处理，[PluginLoader] 都无需关心。
+ * 一个插件要在何时被加载，依赖如何处理，[PluginLoader] 都无需关心.
  *
  * 有关插件的依赖和已加载的插件列表由 [PluginManager] 维护.
  *
diff --git a/docs/Extensions.md b/docs/Extensions.md
index 850c76c96..6958c0c5b 100644
--- a/docs/Extensions.md
+++ b/docs/Extensions.md
@@ -2,8 +2,36 @@
 
 Mirai Console 拥有灵活的 Extensions API，支持扩展 Console 的一些服务。
 
-## 扩展
+Extensions 属于插件开发的进阶内容。
 
+[`Extension`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/Extension.kt
+[`ExtensionPoint`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/ExtensionPoint.kt
+[`PluginComponentStorage`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/PluginComponentStorage.kt
+[`ComponentStorage`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/ComponentStorage.kt
 
+## [扩展][`Extension`]
 
-## 注册扩展
\ No newline at end of file
+### [组件容器][`ComponentStorage`]
+
+容纳插件注册的 [扩展][`Extension`]。
+
+### 注册扩展
+
+插件仅能在 [`onLoad`](Plugins.md#加载) 阶段注册扩展。
+
+示例：
+
+```kotlin
+object MyPlugin : KotlinPlugin( /* ... */ ) {
+    fun PluginComponentStorage.onLoad() {
+        contributePermissionService { /* ... */ }
+        contributePluginLoader { /* ... */ }
+        contribute(ExtensionPoint) { /* ... */ }
+    }
+}
+
+```
+
+### 可用扩展
+
+查看 [extensions](../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/)。每个文件对应一个扩展。
\ No newline at end of file
diff --git a/docs/FrontEnd.md b/docs/FrontEnd.md
index 4287ca861..fd06cbe11 100644
--- a/docs/FrontEnd.md
+++ b/docs/FrontEnd.md
@@ -1 +1,35 @@
-#
\ No newline at end of file
+# Mirai Console Frontend
+
+Mirai Console 前端开发文档。
+
+[`MiraiConsole`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsole.kt
+
+## 实现前端
+
+### 添加编译器设置
+
+在 `build.gradle` 或 `build.gradle.kts` 添加：
+```kotlin
+kotlin {
+    sourceSets.all {
+        languageSettings.useExperimentalAnnotation("net.mamoe.mirai.console.ConsoleFrontEndImplementation")
+    }
+}
+```
+
+此后就可以使用 `net.mamoe.mirai.console.ConsoleFrontEndImplementation` 标记的所有 API。
+
+
+### 实现 Mirai Console
+
+[`MiraiConsole`] 是后端的公开对象，由 [MiraiConsoleImplementationBridge](../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/MiraiConsoleImplementationBridge.kt) 代理，与前端链接。
+
+前端需要实现 [MiraiConsoleImplementation.kt](../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsoleImplementation.kt)。
+
+由于实现前端需要一定的技术能力，相信实现者都能理解源码内注释。
+
+### 启动 Mirai Console
+
+通过 `public fun MiraiConsoleImplementation.start()`。
+
+[MiraiConsoleImplementation.kt: Line 161](../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsoleImplementation.kt#L161)
\ No newline at end of file
diff --git a/docs/PermissionService.md b/docs/PermissionService.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/Permissions.md b/docs/Permissions.md
index e69de29bb..3dfb66204 100644
--- a/docs/Permissions.md
+++ b/docs/Permissions.md
@@ -0,0 +1,141 @@
+# Mirai Console Backend - Permissions
+
+权限系统。
+
+[`PermissionService`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionService.kt
+[`Permission`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/Permission.kt
+[`RootPermission`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/Permission.kt#L82
+[`PermissionId`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionId.kt
+[`PermissionIdNamespace`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionIdNamespace.kt
+[`Permittee`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/Permittee.kt
+[`PermitteeId`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermitteeId.kt
+[`AbstractPermitteeId`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermitteeId.kt#L77
+[`CommandSender`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/CommandSender.kt
+
+## 权限
+
+每个权限都由 [`Permission`] 对象表示。
+
+一个 [`Permission`] 拥有这些信息：
+```kotlin
+interface Permission {
+    val id: PermissionId // 唯一识别 ID
+    val description: String // 描述信息
+    val parent: Permission // 父权限
+}
+```
+
+「权限」表示的意义是 “做一项工作的能力”。如 “执行指令 /stop”，“操作数据库” 都叫作权限。
+
+[`Permission`] 对象由 Console 内置或者由特定权限插件实现。其他插件不能实现 [`Permission`] 接口。
+
+### 权限 ID
+
+```kotlin
+data class PermissionId(
+    val namespace: String, // 命名空间
+    val name: String, // 名称
+)
+```
+
+[`PermissionId`] 是 [`Permission`] 的唯一标识符。知道 [`PermissionId`] 就可以获取到对应的 [`Permission`]。
+
+字符串表示为 "$namespace:$name"，如 "console:command.stop", "*:*"
+
+#### 命名空间
+
+命名空间（“namespace”）用于限定权限的创建者，避免冲突。
+
+一些常见命名空间：
+
+| 用途          | 命名空间      |
+|:-------------|:------------|
+| 根权限         | `"*"`       |
+| Console 内置  | `"console"` |
+| ID 为 A 的插件 | `"A"`       |
+
+#### 名称
+
+名称则表示特定的含义。如一个指令，某一项操作等。
+
+一些常见名称：
+
+| 用途                       | 名称           |
+|:--------------------------|:--------------|
+| 根权限                     | `"*"`         |
+| Console 内置的名为 A 的指令  | `"command.A"` |
+| ID 为 A 的插件的名为 B 的指令 | `"command.B"` |
+
+#### 根权限
+
+[`RootPermission`] 是所有权限的父权限。其 ID 为 "*:*"
+
+## 被许可人
+
+```kotlin
+interface Permittee {
+    val permitteeId: PermitteeId
+}
+```
+
+[`Permittee`] 表示一个可被赋予权限的对象，即 '被许可人'。
+
+[`CommandSender`] 实现 [`Permittee`]。
+
+被许可人自身不持有拥有的权限列表，而是拥有 [`PermitteeId`]，标识自己的身份，供 [权限服务][`PermissionService`] 处理。
+
+**注意**：请不要自主实现 [`Permittee`]。
+
+### 被许可人 ID
+
+```kotlin
+interface PermitteeId {
+    val directParents: Array<out PermitteeId> // 直接父对象
+    fun asString(): String // 转换为字符串表示
+}
+````
+
+[`PermitteeId`] 是被许可人的标识符。
+
+一个这样的标识符即可代表特定的单个 [`Permittee`], 也可以表示多个同类 [`Permittee`].
+
+#### `directParents`
+[`PermitteeId`] 允许拥有多个父对象。在检查权限时会首先检查自己, 再递归检查父类。
+
+#### 衍生类型
+
+[`PermitteeId`] 的实现通常是 [`AbstractPermitteeId`]
+
+在 [`AbstractPermitteeId`] 查看其子类。
+
+### 获取被许可人
+
+通常使用 `CommandSender.permitteeId`。  
+也可以直接构造 [`AbstractPermitteeId`] 的子类。或者在 Kotlin 使用扩展 `User.permitteeId`
+
+## 权限服务
+
+[`PermissionService`] 承载权限的授权和管理。Console 内置一个实现，而权限服务可以由插件提供（见 [扩展](Extensions.md)）。
+
+### 判断权限
+
+在 Kotlin，在该有扩展的对象上 Console 都为它们实现了扩展。可以使用：
+```kotlin
+fun Permittee.hasPermission(Permission): Boolean
+fun Permission.testPermission(Permittee): Boolean
+fun PermitteeId.hasPermission(Permission): Boolean
+fun PermissionId.testPermission(Permittee): Boolean
+fun Permittee.hasPermission(PermissionId): Boolean
+fun Permission.testPermission(PermitteeId): Boolean
+// ... 
+```
+
+请查看 [`PermissionService`] 中的伴生对象。
+
+### 注册权限
+
+每一条指令都会默认自动创建一个权限。
+
+如果希望手动注册一个其他用途的权限，使用 `PermissionService.register`。
+
+**注意**：权限只能在插件 [启用](Plugins.md#启用) 之后才能注册。否则会得到一个异常。
\ No newline at end of file
diff --git a/docs/PluginLoader.md b/docs/PluginLoader.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/Plugins.md b/docs/Plugins.md
index fa588e91d..f04beb5f7 100644
--- a/docs/Plugins.md
+++ b/docs/Plugins.md
@@ -59,7 +59,7 @@ interface Plugin : CommandOwner { // CommandOwner 是空的 interface
 }
 ```
 
-[`Plugin`] 接口拥有强扩展性，以支持 Mirai Console 统一管理使用其他编程语言编写的插件 （详见进阶章节 [实现 PluginLoader](PluginLoader.md)）。
+[`Plugin`] 接口拥有强扩展性，以支持 Mirai Console 统一管理使用其他编程语言编写的插件 （详见进阶章节 [扩展 - PluginLoader](Extensions.md)）。
 
 ## JVM 平台插件接口 - [`JvmPlugin`]
 
diff --git a/docs/README.md b/docs/README.md
index 99ad44576..3125e4e4e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -17,8 +17,6 @@
 ### 后端插件开发进阶
 
 - 扩展 - [Extension 模块和扩展点](Extensions.md)
-- 扩展 - [实现 PluginLoader](PluginLoader.md)
-- 扩展 - [实现 PermissionService](PermissionService.md)
 
 ### 实现前端
 - [FrontEnd](FrontEnd.md)