Add descriptions for permissions

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/BuiltInCommands.kt

@@ -148,7 +148,7 @@ public object BuiltInCommands {
 
     public object PermissionCommand : CompositeCommand(
         ConsoleCommandOwner, "permission", "权限", "perm",
-        description = "Manage permissions",
+        description = "管理权限",
         overrideContext = buildCommandArgumentContext {
             PermitteeId::class with PermitteeIdArgumentParser
             Permission::class with PermissionIdArgumentParser.map { id ->
@@ -159,30 +159,47 @@ public object BuiltInCommands {
         },
     ), BuiltInCommandInternal {
         // TODO: 2020/9/10 improve Permission command
+
+        @Description("授权一个权限")
         @SubCommand("permit", "grant", "add")
-        public suspend fun CommandSender.permit(target: PermitteeId, permission: Permission) {
+        public suspend fun CommandSender.permit(
+            @Name("被许可人 ID") target: PermitteeId,
+            @Name("权限 ID") permission: Permission,
+        ) {
             target.grantPermission(permission)
             sendMessage("OK")
         }
 
+        @Description("取消授权一个权限")
         @SubCommand("cancel", "deny", "remove")
-        public suspend fun CommandSender.cancel(target: PermitteeId, permission: Permission) {
+        public suspend fun CommandSender.cancel(
+            @Name("被许可人 ID") target: PermitteeId,
+            @Name("权限 ID") permission: Permission,
+        ) {
             target.denyPermission(permission, false)
             sendMessage("OK")
         }
 
+        @Description("取消授权一个权限及其所有子权限")
         @SubCommand("cancelAll", "denyAll", "removeAll")
-        public suspend fun CommandSender.cancelAll(target: PermitteeId, permission: Permission) {
+        public suspend fun CommandSender.cancelAll(
+            @Name("被许可人 ID") target: PermitteeId,
+            @Name("权限 ID") permission: Permission,
+        ) {
             target.denyPermission(permission, true)
             sendMessage("OK")
         }
 
+        @Description("查看被授权权限列表")
         @SubCommand("permittedPermissions", "pp", "grantedPermissions", "gp")
-        public suspend fun CommandSender.permittedPermissions(target: PermitteeId) {
+        public suspend fun CommandSender.permittedPermissions(
+            @Name("被许可人 ID") target: PermitteeId,
+        ) {
             val grantedPermissions = target.getPermittedPermissions()
             sendMessage(grantedPermissions.joinToString("\n") { it.id.toString() })
         }
 
+        @Description("查看所有权限列表")
         @SubCommand("listPermissions", "lp")
         public suspend fun CommandSender.listPermissions() {
             sendMessage(PermissionService.INSTANCE.getRegisteredPermissions().joinToString("\n") { it.id.toString() })

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermitteeId.kt

@@ -14,6 +14,7 @@ package net.mamoe.mirai.console.permission
 import kotlinx.serialization.KSerializer
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.builtins.serializer
+import net.mamoe.mirai.console.command.BuiltInCommands
 import net.mamoe.mirai.console.internal.data.map
 import net.mamoe.mirai.console.internal.permission.parseFromStringImpl
 import net.mamoe.mirai.console.permission.AbstractPermitteeId.*
@@ -107,6 +108,33 @@ public interface PermitteeId {
  *
  * - 若指令 A 的权限被授予给 [AnyMember], 那么一个 [ExactMember] 可以执行这个指令.
  *
+ * #### 字符串表示
+ *
+ * 当使用 [PermitteeId.asString] 时, 不同的类型的返回值如下表所示. 这些格式也适用于 [BuiltInCommands.PermissionCommand].
+ *
+ * (不区分大小写. 不区分 Bot).
+ *
+ *
+ * |    被许可人类型    | 字符串表示示例 | 备注                                  |
+ * |:----------------:|:-----------:|:-------------------------------------|
+ * |      控制台       |   console   |                                      |
+ * |      精确群       |   g123456   | 表示群, 而不表示群成员                   |
+ * |      精确好友      |   f123456   | 必须通过好友消息                        |
+ * |    精确临时会话    | t123456.789  | 群 123456 内的成员 789. 必须通过临时会话  |
+ * |     精确群成员     | m123456.789 | 群 123456 内的成员 789. 同时包含临时会话. |
+ * |      精确用户      |   u123456   | 同时包含群成员, 好友, 临时会话            |
+ * |      任意群       |     g*      |                                      |
+ * |  任意群的任意群员   |     m*      |                                      |
+ * |  精确群的任意群员   |  m123456.*  | 群 123456 内的任意成员. 同时包含临时会话.  |
+ * | 任意群的任意临时会话 |     t*      | 必须通过临时会话                        |
+ * | 精确群的任意临时会话 |  t123456.*  | 群 123456 内的任意成员. 必须通过临时会话   |
+ * |      任意好友      |     f*      |                                      |
+ * |      任意用户      |     u*      | 任何人在任何环境                        |
+ * |      任意对象      |      *      | 即任何人, 任何群, 控制台                 |
+ *
+ *
+ * #### 关系图
+ *
  * ```
  *          Console                               AnyContact
  *                                                     ↑

docs/Permissions.md

@@ -108,6 +108,28 @@ interface PermitteeId {
 
 在 [`AbstractPermitteeId`] 查看其子类。
 
+#### 字符串表示
+
+当使用 `PermitteeId.asString` 时, 不同的类型的返回值如下表所示. 这些格式也适用于 [权限指令](#使用内置权限服务指令).  
+(不区分大小写. 不区分 Bot).
+
+|    被许可人类型    | 字符串表示示例 | 备注                                  |
+|:----------------:|:-----------:|:-------------------------------------|
+|      控制台       |   console   |                                      |
+|      精确群       |   g123456   | 表示群, 而不表示群成员                   |
+|      精确好友      |   f123456   | 必须通过好友消息                        |
+|    精确临时会话    | t123456.789  | 群 123456 内的成员 789. 必须通过临时会话  |
+|     精确群成员     | m123456.789 | 群 123456 内的成员 789. 同时包含临时会话. |
+|      精确用户      |   u123456   | 同时包含群成员, 好友, 临时会话            |
+|      任意群       |     g*      |                                      |
+|  任意群的任意群员   |     m*      |                                      |
+|  精确群的任意群员   |  m123456.*  | 群 123456 内的任意成员. 同时包含临时会话.  |
+| 任意群的任意临时会话 |     t*      | 必须通过临时会话                        |
+| 精确群的任意临时会话 |  t123456.*  | 群 123456 内的任意成员. 必须通过临时会话   |
+|      任意好友      |     f*      |                                      |
+|      任意用户      |     u*      | 任何人在任何环境                        |
+|      任意对象      |      *      | 即任何人, 任何群, 控制台                 |
+
 ### 获取被许可人
 
 通常使用 `CommandSender.permitteeId`。  
@@ -138,4 +160,18 @@ fun Permission.testPermission(PermitteeId): Boolean
 
 如果希望手动注册一个其他用途的权限，使用 `PermissionService.register`。
 
-**注意**：权限只能在插件 [启用](Plugins.md#启用) 之后才能注册。否则会得到一个异常。
+**注意**：权限只能在插件 [启用](Plugins.md#启用) 之后才能注册。否则会得到一个异常。
+
+### 使用内置权限服务指令
+
+**根指令**: "/permission", "/perm", "/权限"
+
+```
+/permission cancel <被许可人 ID> <权限 ID>   取消授权一个权限
+/permission cancelall <被许可人 ID> <权限 ID>   取消授权一个权限及其所有子权限
+/permission listpermissions    查看所有权限列表
+/permission permit <被许可人 ID> <权限 ID>   授权一个权限
+/permission permittedpermissions <被许可人 ID>   查看被授权权限列表
+```
+
+其中, 被许可人 ID 使用 [字符串表示](#字符串表示), 权限 ID 参见 [权限 ID](#权限-id)