Rename listener to handler

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/subscriber.kt

@@ -133,7 +133,7 @@ interface Listener<in E : Event> : CompletableJob {
 /**
  * 在指定的 [协程作用域][CoroutineScope] 下创建一个事件监听器, 监听所有 [E] 及其子类事件.
  *
- * 每当 [事件广播][Event.broadcast] 时, [listener] 都会被执行.
+ * 每当 [事件广播][Event.broadcast] 时, [handler] 都会被执行.
  *
  *
  * ### 创建监听
@@ -165,7 +165,7 @@ interface Listener<in E : Event> : CompletableJob {
  * ```
  *
  * #### 在监听器内部停止后续监听
- * 当 [listener] 返回 [ListeningStatus.STOPPED] 时停止监听.
+ * 当 [handler] 返回 [ListeningStatus.STOPPED] 时停止监听.
  * 或 [Listener.complete] 后结束.
  *
  * ### 子类监听
@@ -174,23 +174,23 @@ interface Listener<in E : Event> : CompletableJob {
  * ### 异常处理
  * 事件处理时的 [CoroutineContext] 为调用本函数时的 [receiver][this] 的 [CoroutineScope.coroutineContext].
  * 因此:
- * - 当参数 [listener] 处理抛出异常时, 将会按如下顺序寻找 [CoroutineExceptionHandler] 处理异常:
+ * - 当参数 [handler] 处理抛出异常时, 将会按如下顺序寻找 [CoroutineExceptionHandler] 处理异常:
  *   1. 参数 [coroutineContext]
  *   2. 接收者 [this] 的 [CoroutineScope.coroutineContext]
  *   3. [Event.broadcast] 调用者的 [coroutineContext]
  *   4. 若事件为 [BotEvent], 则从 [BotEvent.bot] 获取到 [Bot], 进而在 [Bot.coroutineContext] 中寻找
  *   5. 若以上四个步骤均无法获取 [CoroutineExceptionHandler], 则使用 [MiraiLogger.Companion] 通过日志记录. 但这种情况理论上不应发生.
  * - 事件处理时抛出异常不会停止监听器.
- * - 建议在事件处理中 (即 [listener] 里) 处理异常,
+ * - 建议在事件处理中 (即 [handler] 里) 处理异常,
  *   或在参数 [coroutineContext] 中添加 [CoroutineExceptionHandler].
  *
  *
  * @param coroutineContext 给事件监听协程的额外的 [CoroutineContext].
  * @param concurrency 并发类型. 查看 [Listener.ConcurrencyKind]
  * @param priority  监听优先级，优先级越高越先执行
- * @param listener 事件处理器. 在接收到事件时会调用这个处理器. 其返回值意义参考 [ListeningStatus]. 其异常处理参考上文
+ * @param handler 事件处理器. 在接收到事件时会调用这个处理器. 其返回值意义参考 [ListeningStatus]. 其异常处理参考上文
  *
- * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [listener]
+ * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [handler]
  *
  * @see syncFromEvent 挂起当前协程, 监听一个事件, 并尝试从这个事件中**同步**一个值
  * @see asyncFromEvent 异步监听一个事件, 并尝试从这个事件中获取一个值.
@@ -212,27 +212,27 @@ inline fun <reified E : Event> CoroutineScope.subscribe(
     coroutineContext: CoroutineContext = EmptyCoroutineContext,
     concurrency: Listener.ConcurrencyKind = LOCKED,
     priority: Listener.EventPriority = NORMAL,
-    noinline listener: suspend E.(E) -> ListeningStatus
-): Listener<E> = subscribe(E::class, coroutineContext, concurrency, priority, listener)
+    noinline handler: suspend E.(E) -> ListeningStatus
+): Listener<E> = subscribe(E::class, coroutineContext, concurrency, priority, handler)
 
 /**
  * 与 [subscribe] 的区别是接受 [eventClass] 参数, 而不使用 `reified` 泛型
  *
  * @see CoroutineScope.subscribe
  *
- * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [listener]
+ * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [handler]
  */
 fun <E : Event> CoroutineScope.subscribe(
     eventClass: KClass<E>,
     coroutineContext: CoroutineContext = EmptyCoroutineContext,
     concurrency: Listener.ConcurrencyKind = LOCKED,
     priority: Listener.EventPriority = NORMAL,
-    listener: suspend E.(E) -> ListeningStatus
-): Listener<E> = eventClass.subscribeInternal(Handler(coroutineContext, concurrency, priority) { it.listener(it); })
+    handler: suspend E.(E) -> ListeningStatus
+): Listener<E> = eventClass.subscribeInternal(Handler(coroutineContext, concurrency, priority) { it.handler(it); })
 
 /**
  * 在指定的 [CoroutineScope] 下订阅所有 [E] 及其子类事件.
- * 每当 [事件广播][Event.broadcast] 时, [listener] 都会被执行.
+ * 每当 [事件广播][Event.broadcast] 时, [handler] 都会被执行.
  *
  * 可在任意时候通过 [Listener.complete] 来主动停止监听.
  * [CoroutineScope] 被关闭后事件监听会被 [取消][Listener.cancel].
@@ -241,7 +241,7 @@ fun <E : Event> CoroutineScope.subscribe(
  * @param coroutineContext 给事件监听协程的额外的 [CoroutineContext]
  * @param priority 处理优先级, 优先级高的先执行
  *
- * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [listener]
+ * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [handler]
  *
  * @see CoroutineScope.subscribe 获取更多说明
  */
@@ -249,8 +249,8 @@ inline fun <reified E : Event> CoroutineScope.subscribeAlways(
     coroutineContext: CoroutineContext = EmptyCoroutineContext,
     concurrency: Listener.ConcurrencyKind = CONCURRENT,
     priority: Listener.EventPriority = NORMAL,
-    noinline listener: suspend E.(E) -> Unit
-): Listener<E> = subscribeAlways(E::class, coroutineContext, concurrency, priority, listener)
+    noinline handler: suspend E.(E) -> Unit
+): Listener<E> = subscribeAlways(E::class, coroutineContext, concurrency, priority, handler)
 
 
 /**
@@ -262,14 +262,14 @@ fun <E : Event> CoroutineScope.subscribeAlways(
     coroutineContext: CoroutineContext = EmptyCoroutineContext,
     concurrency: Listener.ConcurrencyKind = CONCURRENT,
     priority: Listener.EventPriority = NORMAL,
-    listener: suspend E.(E) -> Unit
+    handler: suspend E.(E) -> Unit
 ): Listener<E> = eventClass.subscribeInternal(
-    Handler(coroutineContext, concurrency, priority) { it.listener(it); ListeningStatus.LISTENING }
+    Handler(coroutineContext, concurrency, priority) { it.handler(it); ListeningStatus.LISTENING }
 )
 
 /**
  * 在指定的 [CoroutineScope] 下订阅所有 [E] 及其子类事件.
- * 仅在第一次 [事件广播][Event.broadcast] 时, [listener] 会被执行.
+ * 仅在第一次 [事件广播][Event.broadcast] 时, [handler] 会被执行.
  *
  * 可在任意时候通过 [Listener.complete] 来主动停止监听.
  * [CoroutineScope] 被关闭后事件监听会被 [取消][Listener.cancel].
@@ -283,8 +283,8 @@ fun <E : Event> CoroutineScope.subscribeAlways(
 inline fun <reified E : Event> CoroutineScope.subscribeOnce(
     coroutineContext: CoroutineContext = EmptyCoroutineContext,
     priority: Listener.EventPriority = NORMAL,
-    noinline listener: suspend E.(E) -> Unit
-): Listener<E> = subscribeOnce(E::class, coroutineContext, priority, listener)
+    noinline handler: suspend E.(E) -> Unit
+): Listener<E> = subscribeOnce(E::class, coroutineContext, priority, handler)
 
 /**
  * @see CoroutineScope.subscribeOnce
@@ -293,9 +293,9 @@ fun <E : Event> CoroutineScope.subscribeOnce(
     eventClass: KClass<E>,
     coroutineContext: CoroutineContext = EmptyCoroutineContext,
     priority: Listener.EventPriority = NORMAL,
-    listener: suspend E.(E) -> Unit
+    handler: suspend E.(E) -> Unit
 ): Listener<E> = eventClass.subscribeInternal(
-    Handler(coroutineContext, LOCKED, priority) { it.listener(it); ListeningStatus.STOPPED }
+    Handler(coroutineContext, LOCKED, priority) { it.handler(it); ListeningStatus.STOPPED }
 )
 
 //
@@ -462,7 +462,7 @@ inline fun <reified E : Event> CoroutineScope.subscribeDeprecated(
     coroutineContext = coroutineContext,
     concurrency = concurrency,
     priority = MONITOR,
-    listener = handler
+    handler = handler
 )
 
 @PlannedRemoval("1.2.0")
@@ -480,7 +480,7 @@ fun <E : Event> CoroutineScope.subscribeDeprecated(
     coroutineContext = coroutineContext,
     concurrency = concurrency,
     priority = MONITOR,
-    listener = handler
+    handler = handler
 )
 
 @PlannedRemoval("1.2.0")
@@ -496,7 +496,7 @@ inline fun <reified E : Event> CoroutineScope.subscribeAlwaysDeprecated(
     coroutineContext = coroutineContext,
     concurrency = concurrency,
     priority = MONITOR,
-    listener = listener
+    handler = listener
 )
 
 @PlannedRemoval("1.2.0")
@@ -514,7 +514,7 @@ fun <E : Event> CoroutineScope.subscribeAlwaysDeprecated(
     coroutineContext = coroutineContext,
     concurrency = concurrency,
     priority = MONITOR,
-    listener = listener
+    handler = listener
 )
 
 @PlannedRemoval("1.2.0")
@@ -528,7 +528,7 @@ inline fun <reified E : Event> CoroutineScope.subscribeOnceDeprecated(
 ): Listener<E> = subscribeOnce(
     coroutineContext = coroutineContext,
     priority = MONITOR,
-    listener = listener
+    handler = listener
 )
 
 @PlannedRemoval("1.2.0")
@@ -544,7 +544,7 @@ fun <E : Event> CoroutineScope.subscribeOnceDeprecated(
     eventClass = eventClass,
     coroutineContext = coroutineContext,
     priority = MONITOR,
-    listener = listener
+    handler = listener
 )
 
 @PlannedRemoval("1.2.0")
@@ -561,7 +561,7 @@ inline fun <reified E : BotEvent> Bot.subscribeDeprecated(
     coroutineContext = coroutineContext,
     concurrency = concurrency,
     priority = MONITOR,
-    listener = handler
+    handler = handler
 )
 
 @PlannedRemoval("1.2.0")
@@ -579,7 +579,7 @@ fun <E : BotEvent> Bot.subscribeDeprecated(
     coroutineContext = coroutineContext,
     concurrency = concurrency,
     priority = MONITOR,
-    listener = handler
+    handler = handler
 )
 
 @PlannedRemoval("1.2.0")
@@ -596,7 +596,7 @@ inline fun <reified E : BotEvent> Bot.subscribeAlwaysDeprecated(
     coroutineContext = coroutineContext,
     concurrency = concurrency,
     priority = MONITOR,
-    listener = listener
+    handler = listener
 )
 
 @PlannedRemoval("1.2.0")
@@ -614,7 +614,7 @@ fun <E : BotEvent> Bot.subscribeAlwaysDeprecated(
     coroutineContext = coroutineContext,
     concurrency = concurrency,
     priority = MONITOR,
-    listener = listener
+    handler = listener
 )
 
 @PlannedRemoval("1.2.0")
@@ -628,7 +628,7 @@ inline fun <reified E : BotEvent> Bot.subscribeOnceDeprecated(
 ): Listener<E> = subscribeOnce(
     coroutineContext = coroutineContext,
     priority = MONITOR,
-    listener = listener
+    handler = listener
 )
 
 @PlannedRemoval("1.2.0")
@@ -644,6 +644,6 @@ fun <E : BotEvent> Bot.subscribeOnceDeprecated(
     eventClass = eventClass,
     coroutineContext = coroutineContext,
     priority = MONITOR,
-    listener = listener
+    handler = listener
 )
 // endregion
\ No newline at end of file