Improve implementation docs

mirai-core/src/commonMain/kotlin/network/handler/NetworkHandler.kt

@@ -57,14 +57,12 @@ internal interface NetworkHandler : CoroutineScope {
      * On [State.CONNECTING], [NetworkHandler] establishes a connection with the server while [SsoProcessor] takes responsibility in the single-sign-on process.
      *
      * Successful logon turns state to [State.LOADING], an **open state**, which does nothing by default. Jobs can be *attached* by [StateObserver]s.
-     * For example, attaching a [BotInitProcessor] to handle session-relevant jobs to the [Bot].
+     * For example, attaching a [BotInitProcessor] to handle account-relevant jobs to the [Bot].
      *
-     * Failure during [State.CONNECTING] and [State.LOADING] switches state to [State.CLOSED], on which [NetworkHandler] is considered permanently dead.
+     * Failure during [State.CONNECTING] and [State.LOADING] switches state to [State.CLOSED], on which [NetworkHandler] is considered **permanently dead**.
-     *
+     * The state after finishing of [State.LOADING] is [State.OK]. This state lasts for the majority of time.
-     * The state after finish of [State.LOADING] is [State.OK]. This state lasts for the majority of time.
-     *
-     * When connection is lost (e.g. due to Internet unavailability), it does NOT return to [State.CONNECTING] but to [State.CLOSED]. No attempts is allowed.
      *
+     * When connection is lost (e.g. due to Internet unavailability), it does NOT return to [State.CONNECTING] but to [State.CLOSED]. No reconnection is allowed.
      * Retrial may only be performed in [SelectorNetworkHandler].
      *
      * @see state
@@ -124,9 +122,10 @@ internal interface NetworkHandler : CoroutineScope {
 
 
     /**
-     * Sends [packet] and expects to receive a response from the server.
+     * Sends [packet], suspends and expects to receive a response from the server.
      *
-     * Coroutine suspension may happen if connection if not yet available however, [IllegalStateException] is thrown if [NetworkHandler] is already in [State.CLOSED]
+     * Coroutine suspension may happen if connection is not yet available however,
+     * [IllegalStateException] is thrown if [NetworkHandler] is already in [State.CLOSED] since closure is final.
      *
      * @param attempts ranges `1..INFINITY`
      */
@@ -135,8 +134,9 @@ internal interface NetworkHandler : CoroutineScope {
     /**
      * Sends [packet] and does not expect any response.
      *
-     * Response is still being processed but not passed as a return value of this function, so it does not suspends this function.
+     * Response is still being processed but not passed as a return value of this function, so it does not suspends this function (due to awaiting for the response).
-     * However, coroutine is still suspended if connection if not yet available, and [IllegalStateException] is thrown if [NetworkHandler] is already in [State.CLOSED]
+     * However, coroutine is still suspended if connection is not yet available,
+     * and [IllegalStateException] is thrown if [NetworkHandler] is already in [State.CLOSED] since closure is final.
      */
     suspend fun sendWithoutExpect(packet: OutgoingPacket)
 

mirai-core/src/commonMain/kotlin/network/handler/NetworkHandlerSupport.kt

@@ -111,7 +111,7 @@ internal abstract class NetworkHandlerSupport(
     }
 
     ///////////////////////////////////////////////////////////////////////////
-    // await impl
+    // packets synchronization impl
     ///////////////////////////////////////////////////////////////////////////
 
     protected class PacketListener(

mirai-core/src/commonMain/kotlin/network/handler/selector/AbstractKeepAliveNetworkHandlerSelector.kt

@@ -67,7 +67,7 @@ internal abstract class AbstractKeepAliveNetworkHandlerSelector<H : NetworkHandl
                 NetworkHandler.State.CONNECTING,
                 NetworkHandler.State.INITIALIZED -> {
                     current.resumeConnection() // once finished, it should has been LOADING or OK
-                    check(current.state != thisState) { "State is still $thisState after successful resumeConnection." }
+                    check(current.state != thisState) { "Internal error: State is still $thisState after successful resumeConnection." } // this should not happen.
                     return awaitResumeInstanceImpl(attempted) // does not count for an attempt.
                 }
                 NetworkHandler.State.LOADING -> {

mirai-core/src/commonMain/kotlin/network/handler/selector/NetworkHandlerSelector.kt

@@ -10,9 +10,14 @@
 package net.mamoe.mirai.internal.network.handler.selector
 
 import net.mamoe.mirai.internal.network.handler.NetworkHandler
+import net.mamoe.mirai.internal.network.handler.NetworkHandlerFactory
 
 /**
- * A lazy stateful selector of [NetworkHandler]. This is used as a director([selector][SelectorNetworkHandler.selector]) to [SelectorNetworkHandler].
+ * A director([selector][SelectorNetworkHandler.selector]) of [NetworkHandler].
+ *
+ * It can produce [H] instances (maybe by calling [NetworkHandlerFactory]), to be used by [SelectorNetworkHandler]
+ *
+ * @see SelectorNetworkHandler
  */
 internal interface NetworkHandlerSelector<H : NetworkHandler> {
     /**

mirai-core/src/commonMain/kotlin/network/handler/selector/SelectorNetworkHandler.kt

@@ -19,6 +19,7 @@ import kotlin.coroutines.CoroutineContext
 
 /**
  * A proxy to [NetworkHandler] that delegates calls to instance returned by [NetworkHandlerSelector.awaitResumeInstance].
+ * Selection logic is implemented in [NetworkHandlerSelector].
  *
  * This is useful to implement a delegation of [NetworkHandler]. The functionality of *selection* is provided by the strategy [selector][NetworkHandlerSelector].
  *