KDoc for MiraiConsoleLoggerController

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsoleImplementation.kt

@@ -19,6 +19,7 @@ import net.mamoe.mirai.console.command.ConsoleCommandSender
 import net.mamoe.mirai.console.data.PluginDataStorage
 import net.mamoe.mirai.console.internal.MiraiConsoleImplementationBridge
 import net.mamoe.mirai.console.logging.MiraiConsoleLoggerController
+import net.mamoe.mirai.console.logging.MiraiConsoleLoggerControllerForFrontend
 import net.mamoe.mirai.console.plugin.jvm.JvmPluginLoader
 import net.mamoe.mirai.console.plugin.loader.PluginLoader
 import net.mamoe.mirai.console.util.ConsoleInput
@@ -161,6 +162,11 @@ public interface MiraiConsoleImplementation : CoroutineScope {
      */
     public fun createLoginSolver(requesterBot: Long, configuration: BotConfiguration): LoginSolver
 
+    /**
+     * 日志控制器
+     *
+     * @see [MiraiConsoleLoggerControllerForFrontend]
+     */
     public val loggerController: MiraiConsoleLoggerController
 
     public companion object {

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/logging/MiraiConsoleLoggerController.kt

@@ -16,11 +16,35 @@ import net.mamoe.mirai.utils.MiraiLogger
 import net.mamoe.mirai.utils.SimpleLogger
 import java.util.concurrent.atomic.AtomicReference
 
+/**
+ * 日志控制系统
+ *
+ * @see [MiraiConsoleLoggerControllerPlatformBase]
+ * @see [MiraiConsoleLoggerControllerForFrontend]
+ */
 @ConsoleExperimentalApi
 @ConsoleFrontEndImplementation
 public interface MiraiConsoleLoggerController {
+    /** 是否应该记录该等级的日志 */
     public fun shouldLog(identity: String?, priority: SimpleLogger.LogPriority): Boolean
+    /** 是否应该对 [newLogger] 的结果进行缓存 */
     public val cacheLoggers: Boolean
-    public fun newLoggerImpl(identity: String?): MiraiLogger
-    public fun allocateLoggerRegistration(identity: String?): AtomicReference<Any>
+    /**
+     * 创建一个新的 [MiraiLogger]
+     *
+     * 实现细节:
+     * - 应当直接创建一个新的 [MiraiLogger], 且不进行任何持久性操作,
+     *   例如 放置到字段, 放入任意集合 等
+     * - 即不需要在此方法中把 [MiraiLogger] 放入任意缓存
+     */
+    public fun newLogger(identity: String?): MiraiLogger
+    /**
+     * 获取对应的 Registration
+     *
+     * 实现细节:
+     * - 如果 [identity] 存在对应 Registration, 直接返回先前的 Registration
+     * - [identity] 不存在对应 Registration时, 创建新的 Registration 并存储起来
+     * - 注意并发性
+     */
+    public fun getLoggerRegistration(identity: String?): AtomicReference<Any>
 }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/logging/MiraiConsoleLoggerControllerPlatformBase.kt

@@ -22,15 +22,12 @@ import java.util.concurrent.atomic.AtomicReference
 public abstract class MiraiConsoleLoggerControllerPlatformBase : MiraiConsoleLoggerController {
 
     override fun shouldLog(identity: String?, priority: SimpleLogger.LogPriority): Boolean = true
-
-    override val cacheLoggers: Boolean
-        get() = true
-
+    override val cacheLoggers: Boolean get() = true
     protected val registrations: ConcurrentHashMap<Any, AtomicReference<Any>> = ConcurrentHashMap()
 
     protected object NilIdentityPlaceholder
 
-    override fun allocateLoggerRegistration(identity: String?): AtomicReference<Any> =
+    override fun getLoggerRegistration(identity: String?): AtomicReference<Any> =
         registrations.computeIfAbsent(identity ?: NilIdentityPlaceholder) { AtomicReference() }
 
 }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/logging/MiraiConsoleLoggerUnused.kt

@@ -22,9 +22,9 @@ internal class MiraiConsoleLoggerUnused(
     internal lateinit var delegateLogger: MiraiDelegateLogger
     private val logger: MiraiLogger by lazy {
         val logger = if (controller.cacheLoggers) {
-            val reference = controller.allocateLoggerRegistration(identity)
+            val reference = controller.getLoggerRegistration(identity)
             if (reference.compareAndSet(null, InitializeLock)) {
-                val logger = MiraiConsoleLogger(controller, controller.newLoggerImpl(identity))
+                val logger = MiraiConsoleLogger(controller, controller.newLogger(identity))
                 reference.set(logger)
                 logger
             } else {
@@ -40,7 +40,7 @@ internal class MiraiConsoleLoggerUnused(
                 logger
             }
         } else {
-            MiraiConsoleLogger(controller, controller.newLoggerImpl(identity))
+            MiraiConsoleLogger(controller, controller.newLogger(identity))
         }
         delegateLogger.logger = logger
         logger

backend/mirai-console/src/test/kotlin/net/mamoe/mirai/console/TestMiraiConosle.kt

@@ -74,7 +74,7 @@ fun initTestEnvironment() {
 
         override val loggerController: MiraiConsoleLoggerController = object:MiraiConsoleLoggerControllerPlatformBase(){
             override fun shouldLog(identity: String?, priority: SimpleLogger.LogPriority): Boolean = true
-            override fun newLoggerImpl(identity: String?): MiraiLogger = PlatformLogger(identity)
+            override fun newLogger(identity: String?): MiraiLogger = PlatformLogger(identity)
         }
 
         override val coroutineContext: CoroutineContext = SupervisorJob() + CoroutineExceptionHandler { _, throwable ->

frontend/mirai-console-terminal/src/main/kotlin/net/mamoe/mirai/console/terminal/MiraiConsoleImplementationTerminal.kt

@@ -84,7 +84,7 @@ class MiraiConsoleImplementationTerminal
     }
 
     override val loggerController: MiraiConsoleLoggerController = object : MiraiConsoleLoggerControllerForFrontend() {
-        override fun newLoggerImpl(identity: String?): MiraiLogger = LoggerCreator(identity)
+        override fun newLogger(identity: String?): MiraiLogger = LoggerCreator(identity)
     }
 
     init {