From dab3448fab43c6b525d8f27ac60e7692752f0818 Mon Sep 17 00:00:00 2001
From: Him188 <Him188@mamoe.net>
Date: Sun, 1 Mar 2020 18:17:00 +0800
Subject: [PATCH] Add docs
---
.../androidMain/kotlin/net/mamoe/mirai/Bot.kt | 2 +-
.../kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt | 80 ++++++++++++++++++-
.../commonMain/kotlin/net.mamoe.mirai/Bot.kt | 2 +-
.../src/jvmMain/kotlin/net/mamoe/mirai/Bot.kt | 2 +-
.../kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt | 80 ++++++++++++++++++-
5 files changed, 157 insertions(+), 9 deletions(-)
diff --git a/mirai-core/src/androidMain/kotlin/net/mamoe/mirai/Bot.kt b/mirai-core/src/androidMain/kotlin/net/mamoe/mirai/Bot.kt
index 4bdcfa03d..69cc0cae8 100644
--- a/mirai-core/src/androidMain/kotlin/net/mamoe/mirai/Bot.kt
+++ b/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
diff --git a/mirai-core/src/androidMain/kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt b/mirai-core/src/androidMain/kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt
index 3040b434a..1c1ac3ebd 100644
--- a/mirai-core/src/androidMain/kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt
+++ b/mirai-core/src/androidMain/kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt
@@ -1,15 +1,20 @@
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) }
diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/Bot.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/Bot.kt
index 391bfc6b0..bc7b95c6f 100644
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/Bot.kt
+++ b/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
diff --git a/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/Bot.kt b/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/Bot.kt
index 2265ff2fd..f8c267649 100644
--- a/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/Bot.kt
+++ b/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
diff --git a/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt b/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt
index 3040b434a..1c1ac3ebd 100644
--- a/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt
+++ b/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/BotJavaHappyAPI.kt
@@ -1,15 +1,20 @@
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) }