Improve docs

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/BotFactory.kt

@@ -14,6 +14,7 @@ package net.mamoe.mirai
 import net.mamoe.mirai.utils.BotConfiguration
 import net.mamoe.mirai.utils.Context
 import kotlin.jvm.JvmName
+import kotlin.jvm.JvmSynthetic
 
 /**
  * 构造 [Bot] 的工厂. 这是 [Bot] 唯一的构造方式.
@@ -49,6 +50,7 @@ expect interface BotFactory {
 /**
  * 使用指定的 [配置][configuration] 构造 [Bot] 实例
  */
+@JvmSynthetic
 inline fun BotFactory.Bot(
     context: Context,
     qq: Long,
@@ -59,6 +61,7 @@ inline fun BotFactory.Bot(
 /**
  * 使用指定的 [配置][configuration] 构造 [Bot] 实例
  */
+@JvmSynthetic
 inline fun BotFactory.Bot(
     context: Context,
     qq: Long,

mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/BotFactory.kt

@@ -12,7 +12,13 @@ import net.mamoe.mirai.utils.ContextImpl
  *
  * 请添加模块依赖 `mirai-core-qqandroid` 以获取协议支持.
  *
+ * ### 自动选择协议模块并构造 [Bot]
+ * 在 Kotlin 使用包级函数 [Bot], 在 Java 使用 `BotFactoryJvm.newBot`
+ *
  * mirai 通过 [Class.forName] 查找可用的协议实现, 如 `net.mamoe.mirai.qqandroid.QQAndroid`
+ *
+ * ### 手动选择协议模块并构造 [Bot]
+ * 引用 `net.mamoe.mirai.qqandroid.QQAndroid` 并使用其成员函数 [Bot]
  */
 actual interface BotFactory {
     /**
@@ -39,35 +45,8 @@ actual interface BotFactory {
 
 }
 
-
-// Do not use ServiceLoader. Probably not working on MPP
-@PublishedApi
-internal val factory: BotFactory = run {
-    runCatching {
-        Class.forName("net.mamoe.mirai.timpc.TIMPC").kotlin.objectInstance as BotFactory
-    }.getOrElse {
-        runCatching {
-            Class.forName("net.mamoe.mirai.qqandroid.QQAndroid").kotlin.objectInstance as BotFactory
-        }.getOrNull()
-    }
-} ?: error(
-    """
-    No BotFactory found. Please ensure that you've added dependency of protocol modules.
-    Available modules:
-    - net.mamoe:mirai-core-timpc (stays at 0.12.0)
-    - net.mamoe:mirai-core-qqandroid (recommended)
-    You should have at lease one protocol module installed.
-    -------------------------------------------------------
-    找不到 BotFactory. 请确保你依赖了至少一个协议模块.
-    可用的协议模块: 
-    - net.mamoe:mirai-core-timpc (0.12.0 后停止更新)
-    - net.mamoe:mirai-core-qqandroid (推荐)
-    请添加上述任一模块的依赖(与 mirai-core 版本相同)
-    """.trimIndent()
-)
-
 /**
- * 加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
+ * 自动加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
  */
 @JvmName("newBot")
 @JvmOverloads
@@ -75,7 +54,7 @@ fun Bot(context: Context, qq: Long, password: String, configuration: BotConfigur
     factory.Bot(context, qq, password, configuration)
 
 /**
- * 加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
+ * 自动加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
  */
 @JvmSynthetic
 inline fun Bot(context: Context, qq: Long, password: String, configuration: (BotConfiguration.() -> Unit)): Bot =
@@ -83,7 +62,7 @@ inline fun Bot(context: Context, qq: Long, password: String, configuration: (Bot
 
 
 /**
- * 加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
+ * 自动加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
  */
 @JvmName("newBot")
 @JvmOverloads
@@ -91,7 +70,7 @@ fun Bot(qq: Long, password: String, configuration: BotConfiguration = BotConfigu
     factory.Bot(ContextImpl(), qq, password, configuration)
 
 /**
- * 加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
+ * 自动加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
  */
 @JvmSynthetic
 inline fun Bot(qq: Long, password: String, configuration: (BotConfiguration.() -> Unit)): Bot =
@@ -99,7 +78,7 @@ inline fun Bot(qq: Long, password: String, configuration: (BotConfiguration.() -
 
 
 /**
- * 加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
+ * 自动加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
  */
 @JvmName("newBot")
 @JvmOverloads
@@ -112,7 +91,7 @@ fun Bot(
     factory.Bot(context, qq, passwordMd5, configuration)
 
 /**
- * 加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
+ * 自动加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
  */
 @JvmSynthetic
 inline fun Bot(context: Context, qq: Long, passwordMd5: ByteArray, configuration: (BotConfiguration.() -> Unit)): Bot =
@@ -120,7 +99,7 @@ inline fun Bot(context: Context, qq: Long, passwordMd5: ByteArray, configuration
 
 
 /**
- * 加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
+ * 自动加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
  */
 @JvmName("newBot")
 @JvmOverloads
@@ -128,8 +107,38 @@ fun Bot(qq: Long, passwordMd5: ByteArray, configuration: BotConfiguration = BotC
     factory.Bot(ContextImpl(), qq, passwordMd5, configuration)
 
 /**
- * 加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
+ * 自动加载现有协议的 [BotFactory], 并使用指定的 [配置][configuration] 构造 [Bot] 实例
  */
 @JvmSynthetic
 inline fun Bot(qq: Long, passwordMd5: ByteArray, configuration: (BotConfiguration.() -> Unit)): Bot =
-    factory.Bot(ContextImpl(), qq, passwordMd5, BotConfiguration().apply(configuration))
+    factory.Bot(ContextImpl(), qq, passwordMd5, BotConfiguration().apply(configuration))
\ No newline at end of file
+
+
+
+
+
+// Do not use ServiceLoader. Probably not working on MPP
+@PublishedApi
+internal val factory: BotFactory = run {
+    runCatching {
+        Class.forName("net.mamoe.mirai.timpc.TIMPC").kotlin.objectInstance as BotFactory
+    }.getOrElse {
+        runCatching {
+            Class.forName("net.mamoe.mirai.qqandroid.QQAndroid").kotlin.objectInstance as BotFactory
+        }.getOrNull()
+    }
+} ?: error(
+    """
+    No BotFactory found. Please ensure that you've added dependency of protocol modules.
+    Available modules:
+    - net.mamoe:mirai-core-timpc (stays at 0.12.0)
+    - net.mamoe:mirai-core-qqandroid (recommended)
+    You should have at lease one protocol module installed.
+    -------------------------------------------------------
+    找不到 BotFactory. 请确保你依赖了至少一个协议模块.
+    可用的协议模块: 
+    - net.mamoe:mirai-core-timpc (0.12.0 后停止更新)
+    - net.mamoe:mirai-core-qqandroid (推荐)
+    请添加上述任一模块的依赖(与 mirai-core 版本相同)
+    """.trimIndent()
+)
\ No newline at end of file