Update docs

yanfd · Mar 21, 2021 · 39015d6 · 39015d6
1 parent 95d879c
commit 39015d6
Show file tree

Hide file tree

Showing 10 changed files with 56 additions and 29 deletions.
diff --git a/docs/Bots.md b/docs/Bots.md
@@ -228,4 +228,4 @@ contactListCache.setSaveIntervalMillis(60000) // 可选设置有更新时的保
 
 > 下一步，[Contacts](Contacts.md)
 >
-> [回到 Mirai 文档索引](README.md#mirai-core-api-文档)
+> [回到 Mirai 文档索引](CoreAPI.md)
diff --git a/docs/Contacts.md b/docs/Contacts.md
@@ -24,4 +24,4 @@
 
 > 下一步，[Events](Events.md)
 >
-> [回到 Mirai 文档索引](README.md#mirai-core-api-文档)
+> [回到 Mirai 文档索引](CoreAPI.md)
diff --git a/docs/CoreAPI.md b/docs/CoreAPI.md
@@ -0,0 +1,14 @@
+# Mirai - Core API
+
+> 本文档适用于 mirai 2.x 版本  
+> 要由 mirai 1.x 迁移到 2.x，请阅读 [MigrationFrom1x.md](MigrationFrom1x.md)
+
+> 在 GitHub 默认看到的是最新版本的文档，可能不适用于旧版本。  
+> 可以将 URL `https://github.com/mamoe/mirai/blob/2.4.2/docs/README.md` 中的 `2.4.2` 替换为其他版本来查看对应文档。
+
+- 机器人 [Bots](Bots.md)
+- 联系人 [Contacts](Contacts.md)
+- 事件  [Events](Events.md)
+- 消息  [Messages](Messages.md)
+
+> 希望改进文档? 请在 [#848](https://github.com/mamoe/mirai/discussions/848) 提出建议
diff --git a/docs/Events.md b/docs/Events.md
@@ -39,22 +39,27 @@ Mirai 以事件驱动。
 
 如果你了解事件且不希望详细阅读，可以立即仿照下面示例创建事件监听并跳过本章节。
 
-Kotlin
+### Kotlin
+
 ```kotlin
 // 事件监听器是协程任务。如果你有 CoroutineScope，可从 scope 继承生命周期管理和 coroutineContext
 GlobalEventChannel.parentScope(coroutineScope).subscribeAlways<GroupMessageEvent> { event ->
     // this: GroupMessageEvent
     // event: GroupMessageEvent
     subject.sendMessage("Hello!")
 }
+// `GlobalEventChannel.parentScope(coroutineScope)` 也可以替换为使用扩展 `coroutineScope.globalEventChannel()`, 根据个人习惯选择
+
+
 
 // 如果不想限制生命周期，可获取 listener 处理
 val listener: CompletableJob = GlobalEventChannel.subscribeAlways<GroupMessageEvent> { event -> }
 
 listener.complete() // 停止监听
 ```
 
-Java
+### Java
+
 ```java
 // 创建监听
 Listener listener = GlobalEventChannel.INSTANCE.subscribeAlways(GroupMessageEvent.class, event -> {
@@ -75,12 +80,12 @@ listener.complete(); // 停止监听
 
 **`GlobalEventChannel` 会监听到来自所有 `Bot` 的事件，如果只希望监听某一个 bot，请使用 `bot.eventChannel`。**
 
-> 现在你可以继续阅读详细了解事件，或：
+> 你已经了解了基本事件操作。现在你可以继续阅读通道处理和扩展等内容，或：
 >
 > - 跳到下一章 [Messages](Messages.md)
 > - [查看事件列表](../mirai-core-api/src/commonMain/kotlin/event/events/README.md#事件)
-> - 回到 [目录](#目录)  
-> - [回到 Mirai 文档索引](README.md#mirai-core-api-文档)
+> - [回到事件文档目录](#目录)
+> - [回到 Mirai 文档索引](CoreAPI.md)
 
 ## 事件通道
 
@@ -515,4 +520,4 @@ reply("复读模式结束")
 
 > 下一步，[Messages](Messages.md)
 >
-> [回到 Mirai 文档索引](README.md#mirai-core-api-文档)
+> [回到 Mirai 文档索引](CoreAPI.md)
diff --git a/docs/Messages.md b/docs/Messages.md
@@ -421,4 +421,4 @@ new PlainText("[mirai:atall]").serializeToMiraiCode() // \[mirai\:atall\]
 
 > 回到 [目录](#目录)
 >
-> [回到 Mirai 文档索引](README.md#mirai-core-api-文档)
+> [回到 Mirai 文档索引](CoreAPI.md)
diff --git a/docs/MigrationFrom1x.md b/docs/MigrationFrom1x.md
@@ -63,6 +63,8 @@
 
 至此你已经成功升级到了 mirai 2.0。[回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发)
 
+----
+
 ## 使用 Java
 
 **请依次按如下步骤更新以下几个版本**

diff --git a/docs/Preparations.md b/docs/Preparations.md
@@ -1,6 +1,6 @@
 # Mirai - Preparations
 
-本章节介绍 Mirai 的 JVM 环境和开发准备工作。预计阅读时间 2 分钟。
+本章节介绍 Mirai 的 JVM 环境和开发准备工作。
 
 ## JVM 环境要求
 
@@ -10,7 +10,7 @@
 
 **但注意不要使用 Oracle JDK**（[原因](https://github.com/mamoe/mirai/discussions/779)），可以使用其他任何 JDK。
 
-> 下载 JDK：
+> 要下载 JDK：
 > - 手动下载安装如 [AdoptOpenJDK](https://adoptopenjdk.net/)
 > - 自动在 IntelliJ IDEA `Project Structure`(`Ctrl+Shift+Alt+S`) -> `SDKs` -> `+` -> `Download JDK` 下载安装
 
@@ -26,7 +26,7 @@
 <!--[Kotlin Jvm Blocking Bridge-JB]: https://plugins.jetbrains.com/plugin/14816-kotlin-jvm-blocking-bridge-->
 <!--[Kotlin Jvm Blocking Bridge-OK]: https://plugins.jetbrains.com/embeddable/install/14816-->
 
-推荐使用 [IntelliJ IDEA](https://www.jetbrains.com/idea/) 或 [Android Studio](https://developer.android.com/studio)。Mirai 提供 IntelliJ 插件来提升开发体验。
+推荐使用 [IntelliJ IDEA](https://www.jetbrains.com/idea/) 或 [Android Studio](https://developer.android.com/studio)。Mirai 提供 IDE 插件来提升开发体验。
 
 |          插件名           |                         描述                         |               一键安装                |         JetBrains 插件仓库          |
 |:------------------------:|:---------------------------------------------------:|:-----------------------------------:|:----------------------------------:|

diff --git a/docs/README.md b/docs/README.md
@@ -4,7 +4,7 @@
 
 ## 生态
 
-**[Mirai 生态概览](mirai-ecology.md)**
+请先阅读 **[Mirai 生态概览](mirai-ecology.md)**。
 
 ## 社区 SDK
 
@@ -66,14 +66,16 @@
 
 ## JVM 平台 Mirai 开发
 
-**为了避免遇到各种问题，请仔细阅读。**
+**为了避免遇到各种问题，请逐步仔细阅读。**
 
-1. [JVM 环境和开发准备工作（2 分钟）](Preparations.md#mirai---preparations)
+1. [JVM 环境和开发准备工作](Preparations.md#mirai---preparations)
 
-2. **配置项目依赖** （二选一）
-   - 要把 mirai-core 嵌入一个应用使用，请阅读 [配置项目依赖](ConfiguringProjects.md)。
-   - 要为 [`mirai-console`] 框架开发插件，请阅读 [mirai-console 的配置插件项目](https://github.com/mamoe/mirai-console/blob/master/docs/ConfiguringProjects.md)。
-3. 阅读 API 文档（见下文）
+2. 选择框架
+   - 若要将 mirai 当做依赖库嵌入你的应用使用，则需要使用 mirai-core，请阅读 [配置项目依赖](ConfiguringProjects.md)。
+
+   - 若要以插件模式开发，可以使用 mirai-console，请阅读 [mirai-console 的配置插件项目](https://github.com/mamoe/mirai-console/blob/master/docs/ConfiguringProjects.md)。
+
+4. 阅读 API 文档（见下文）
 
 
 > 如果你不知道 `mirai-core` 或 [`mirai-console`] 是什么，请阅读 [Mirai 生态概览](mirai-ecology.md)。
@@ -87,11 +89,4 @@
 
 ### mirai-core API 文档
 
-> *适用于 2.x 版本*
-
-- [Bots](Bots.md)
-- [Contacts](Contacts.md)
-- [Events](Events.md)
-- [Messages](Messages.md)
-
-> 希望改进文档? 请在 [#848](https://github.com/mamoe/mirai/discussions/848) 提出建议
+请在 [CoreAPI.md](CoreAPI.md) 阅读 JVM 平台的 mirai-core-api 使用文档。
diff --git a/docs/mirai-ecology.md b/docs/mirai-ecology.md
@@ -127,4 +127,15 @@ mirai-console-loader 应运而生，它的工作就是简化 console 启动流
 
 实体关系图采用 [Mermaid](https://github.com/mermaid-js/mermaid) 绘制。
 
-> [回到 Mirai 文档索引](README.md#mirai-core-api-文档)
+> [回到 Mirai 文档索引](CoreAPI.md)
+
+### 变更记录
+
+当前版本：`1.2.0` (2021/1/24)
+
+- `1.0.0`: 2020/12/13
+  - [PR 初始版本](https://github.com/mamoe/mirai/pull/710)
+- `1.1.0`: 2021/1/13
+  - 增加了作者信息
+- `1.2.0`: 2021/1/24
+  - 进行了语言精简, 简化关系图
diff --git a/mirai-console b/mirai-console
-Original file line number
+Diff line change
@@ Expand Up / @@ -63,6 +63,8 @@ @@
     至此你已经成功升级到了 mirai 2.0。[回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发)
+    ----
     ## 使用 Java
     **请依次按如下步骤更新以下几个版本**
@@ Expand Down @@
+24 −13		docs/ConfiguringProjects.md
+1 −1		docs/Plugins.md
+6 −6		tools/gradle-plugin/README.md