Add docs

mirai-core/src/androidMain/kotlin/net/mamoe/mirai/Bot.kt

@@ -147,7 +147,7 @@ actual abstract class Bot actual constructor() : CoroutineScope, LowLevelBotAPIA
     actual abstract val network: BotNetworkHandler
 
     /**
-     * 挂起直到 [Bot] 下线.
+     * 挂起协程直到 [Bot] 下线.
      */
     @JvmName("joinSuspend")
     @JvmSynthetic

mirai-core/src/androidMain/kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt

 package net.mamoe.mirai
 
 import kotlinx.coroutines.*
+import net.mamoe.mirai.contact.PermissionDeniedException
+import net.mamoe.mirai.contact.recall
 import net.mamoe.mirai.data.AddFriendResult
+import net.mamoe.mirai.message.MessageReceipt
 import net.mamoe.mirai.message.data.Image
 import net.mamoe.mirai.message.data.MessageChain
 import net.mamoe.mirai.message.data.MessageSource
+import net.mamoe.mirai.network.LoginFailedException
 import net.mamoe.mirai.utils.MiraiExperimentalAPI
 import net.mamoe.mirai.utils.MiraiInternalAPI
 import java.util.concurrent.Future
 import java.util.concurrent.TimeUnit
 import java.util.concurrent.TimeoutException
+import kotlin.coroutines.CoroutineContext
 
 /**
  * [Bot] 中为了让 Java 使用者调用更方便的 API 列表.
@@ -30,42 +35,99 @@ actual abstract class BotJavaHappyAPI actual constructor() {
         return (this as Bot).run { future(block) }
     }
 
-
+    /**
+     * 登录, 或重新登录.
+     * 这个函数总是关闭一切现有网路任务, 然后重新登录并重新缓存好友列表和群列表.
+     *
+     * 一般情况下不需要重新登录. Mirai 能够自动处理掉线情况.
+     *
+     * 最终调用 [net.mamoe.mirai.network.BotNetworkHandler.relogin]
+     *
+     * @throws LoginFailedException
+     */
     @JvmName("login")
     fun __loginBlockingForJava__() {
         runBlocking { login() }
     }
 
+    /**
+     * 撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息.
+     *
+     * [Bot] 撤回自己的消息不需要权限.
+     * [Bot] 撤回群员的消息需要管理员权限.
+     *
+     * @param source 消息源. 可从 [MessageReceipt.source] 获得, 或从消息事件中的 [MessageChain] 获得.
+     *
+     * @throws PermissionDeniedException 当 [Bot] 无权限操作时
+     *
+     * @see Bot.recall (扩展函数) 接受参数 [MessageChain]
+     */
     @JvmName("recall")
     fun __recallBlockingForJava__(source: MessageSource) {
         runBlocking { recall(source) }
     }
 
+    /**
+     * 撤回这条消息.
+     * 根据 [message] 内的 [MessageSource] 进行相关判断.
+     *
+     * [Bot] 撤回自己的消息不需要权限.
+     * [Bot] 撤回群员的消息需要管理员权限.
+     *
+     * @throws PermissionDeniedException 当 [Bot] 无权限操作时
+     * @see Bot.recall
+     */
     @JvmName("recall")
-    fun __recallBlockingForJava__(source: MessageChain) {
-        runBlocking { recall(source) }
+    fun __recallBlockingForJava__(message: MessageChain) {
+        runBlocking { recall(message) }
     }
 
+    /**
+     * 在一段时间后撤回这条消息.
+     * 将根据 [MessageSource.groupId] 判断消息是群消息还是好友消息.
+     *
+     * @param millis 延迟的时间, 单位为毫秒
+     * @see recall
+     */
     @JvmName("recallIn")
     fun __recallIn_MemberForJava__(source: MessageSource, millis: Long) {
         runBlocking { recallIn(source, millis) }
     }
 
+    /**
+     * 在一段时间后撤回这条消息.
+     *
+     * @param millis 延迟的时间, 单位为毫秒
+     * @param coroutineContext 额外的 [CoroutineContext]
+     * @see recall
+     */
     @JvmName("recallIn")
     fun __recallIn_MemberForJava__(source: MessageChain, millis: Long) {
         runBlocking { recallIn(source, millis) }
     }
 
+    /**
+     * 获取图片下载链接
+     */
     @JvmName("queryImageUrl")
     fun __queryImageUrlBlockingForJava__(image: Image): String {
         return runBlocking { queryImageUrl(image) }
     }
 
+    /**
+     * 阻塞当前线程直到 [Bot] 下线.
+     */
     @JvmName("join")
     fun __joinBlockingForJava__() {
         runBlocking { join() }
     }
 
+    /**
+     * 添加一个好友
+     *
+     * @param message 若需要验证请求时的验证消息.
+     * @param remark 好友备注
+     */
     @JvmOverloads
     @JvmName("addFriend")
     fun __addFriendBlockingForJava__(
@@ -77,21 +139,33 @@ actual abstract class BotJavaHappyAPI actual constructor() {
         return runBlocking { addFriend(id, message, remark) }
     }
 
+    /**
+     * 异步调用 [__loginBlockingForJava__]
+     */
     @JvmName("loginAsync")
     fun __loginAsyncForJava__(): Future<Unit> {
         return future { login() }
     }
 
+    /**
+     * 异步调用 [__recallBlockingForJava__]
+     */
     @JvmName("recallAsync")
     fun __recallAsyncForJava__(source: MessageSource): Future<Unit> {
         return future { recall(source) }
     }
 
+    /**
+     * 异步调用 [__recallBlockingForJava__]
+     */
     @JvmName("recallAsync")
     fun __recallAsyncForJava__(source: MessageChain): Future<Unit> {
         return future { recall(source) }
     }
 
+    /**
+     * 异步调用 [__queryImageUrlBlockingForJava__]
+     */
     @JvmName("queryImageUrlAsync")
     fun __queryImageUrlAsyncForJava__(image: Image): Future<String> {
         return future { queryImageUrl(image) }

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

@@ -150,7 +150,7 @@ expect abstract class Bot() : CoroutineScope, LowLevelBotAPIAccessor {
     abstract val network: BotNetworkHandler
 
     /**
-     * 挂起直到 [Bot] 下线.
+     * 挂起协程直到 [Bot] 下线.
      */
     @JvmName("joinSuspend")
     @JvmSynthetic

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

@@ -157,7 +157,7 @@ actual abstract class Bot actual constructor() : CoroutineScope, LowLevelBotAPIA
     actual abstract val network: BotNetworkHandler
 
     /**
-     * 挂起直到 [Bot] 下线.
+     * 挂起协程直到 [Bot] 下线.
      */
     @JvmName("joinSuspend")
     @JvmSynthetic

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

 package net.mamoe.mirai
 
 import kotlinx.coroutines.*
+import net.mamoe.mirai.contact.PermissionDeniedException
+import net.mamoe.mirai.contact.recall
 import net.mamoe.mirai.data.AddFriendResult
+import net.mamoe.mirai.message.MessageReceipt
 import net.mamoe.mirai.message.data.Image
 import net.mamoe.mirai.message.data.MessageChain
 import net.mamoe.mirai.message.data.MessageSource
+import net.mamoe.mirai.network.LoginFailedException
 import net.mamoe.mirai.utils.MiraiExperimentalAPI
 import net.mamoe.mirai.utils.MiraiInternalAPI
 import java.util.concurrent.Future
 import java.util.concurrent.TimeUnit
 import java.util.concurrent.TimeoutException
+import kotlin.coroutines.CoroutineContext
 
 /**
  * [Bot] 中为了让 Java 使用者调用更方便的 API 列表.
@@ -30,42 +35,99 @@ actual abstract class BotJavaHappyAPI actual constructor() {
         return (this as Bot).run { future(block) }
     }
 
-
+    /**
+     * 登录, 或重新登录.
+     * 这个函数总是关闭一切现有网路任务, 然后重新登录并重新缓存好友列表和群列表.
+     *
+     * 一般情况下不需要重新登录. Mirai 能够自动处理掉线情况.
+     *
+     * 最终调用 [net.mamoe.mirai.network.BotNetworkHandler.relogin]
+     *
+     * @throws LoginFailedException
+     */
     @JvmName("login")
     fun __loginBlockingForJava__() {
         runBlocking { login() }
     }
 
+    /**
+     * 撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息.
+     *
+     * [Bot] 撤回自己的消息不需要权限.
+     * [Bot] 撤回群员的消息需要管理员权限.
+     *
+     * @param source 消息源. 可从 [MessageReceipt.source] 获得, 或从消息事件中的 [MessageChain] 获得.
+     *
+     * @throws PermissionDeniedException 当 [Bot] 无权限操作时
+     *
+     * @see Bot.recall (扩展函数) 接受参数 [MessageChain]
+     */
     @JvmName("recall")
     fun __recallBlockingForJava__(source: MessageSource) {
         runBlocking { recall(source) }
     }
 
+    /**
+     * 撤回这条消息.
+     * 根据 [message] 内的 [MessageSource] 进行相关判断.
+     *
+     * [Bot] 撤回自己的消息不需要权限.
+     * [Bot] 撤回群员的消息需要管理员权限.
+     *
+     * @throws PermissionDeniedException 当 [Bot] 无权限操作时
+     * @see Bot.recall
+     */
     @JvmName("recall")
-    fun __recallBlockingForJava__(source: MessageChain) {
-        runBlocking { recall(source) }
+    fun __recallBlockingForJava__(message: MessageChain) {
+        runBlocking { recall(message) }
     }
 
+    /**
+     * 在一段时间后撤回这条消息.
+     * 将根据 [MessageSource.groupId] 判断消息是群消息还是好友消息.
+     *
+     * @param millis 延迟的时间, 单位为毫秒
+     * @see recall
+     */
     @JvmName("recallIn")
     fun __recallIn_MemberForJava__(source: MessageSource, millis: Long) {
         runBlocking { recallIn(source, millis) }
     }
 
+    /**
+     * 在一段时间后撤回这条消息.
+     *
+     * @param millis 延迟的时间, 单位为毫秒
+     * @param coroutineContext 额外的 [CoroutineContext]
+     * @see recall
+     */
     @JvmName("recallIn")
     fun __recallIn_MemberForJava__(source: MessageChain, millis: Long) {
         runBlocking { recallIn(source, millis) }
     }
 
+    /**
+     * 获取图片下载链接
+     */
     @JvmName("queryImageUrl")
     fun __queryImageUrlBlockingForJava__(image: Image): String {
         return runBlocking { queryImageUrl(image) }
     }
 
+    /**
+     * 阻塞当前线程直到 [Bot] 下线.
+     */
     @JvmName("join")
     fun __joinBlockingForJava__() {
         runBlocking { join() }
     }
 
+    /**
+     * 添加一个好友
+     *
+     * @param message 若需要验证请求时的验证消息.
+     * @param remark 好友备注
+     */
     @JvmOverloads
     @JvmName("addFriend")
     fun __addFriendBlockingForJava__(
@@ -77,21 +139,33 @@ actual abstract class BotJavaHappyAPI actual constructor() {
         return runBlocking { addFriend(id, message, remark) }
     }
 
+    /**
+     * 异步调用 [__loginBlockingForJava__]
+     */
     @JvmName("loginAsync")
     fun __loginAsyncForJava__(): Future<Unit> {
         return future { login() }
     }
 
+    /**
+     * 异步调用 [__recallBlockingForJava__]
+     */
     @JvmName("recallAsync")
     fun __recallAsyncForJava__(source: MessageSource): Future<Unit> {
         return future { recall(source) }
     }
 
+    /**
+     * 异步调用 [__recallBlockingForJava__]
+     */
     @JvmName("recallAsync")
     fun __recallAsyncForJava__(source: MessageChain): Future<Unit> {
         return future { recall(source) }
     }
 
+    /**
+     * 异步调用 [__queryImageUrlBlockingForJava__]
+     */
     @JvmName("queryImageUrlAsync")
     fun __queryImageUrlAsyncForJava__(image: Image): Future<String> {
         return future { queryImageUrl(image) }