From 2ccccca4c862261f6ff5f249abb5f661277f9d43 Mon Sep 17 00:00:00 2001
From: Sascha Peilicke <sascha@peilicke.de>
Date: Mon, 25 Mar 2024 21:12:38 +0100
Subject: [PATCH] Improve documentation

---
 .../kotlin/saschpe/log4k/ConsoleLogger.kt     |  3 +++
 .../commonMain/kotlin/saschpe/log4k/Log.kt    | 21 +++++++++++++++++--
 .../kotlin/saschpe/log4k/LoggedTest.kt        |  8 ++++---
 3 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/log4k/src/commonMain/kotlin/saschpe/log4k/ConsoleLogger.kt b/log4k/src/commonMain/kotlin/saschpe/log4k/ConsoleLogger.kt
index de9e497..0766b8c 100644
--- a/log4k/src/commonMain/kotlin/saschpe/log4k/ConsoleLogger.kt
+++ b/log4k/src/commonMain/kotlin/saschpe/log4k/ConsoleLogger.kt
@@ -1,3 +1,6 @@
 package saschpe.log4k
 
+/**
+ * Log to the platform-specific console.
+ */
 expect class ConsoleLogger() : Logger
diff --git a/log4k/src/commonMain/kotlin/saschpe/log4k/Log.kt b/log4k/src/commonMain/kotlin/saschpe/log4k/Log.kt
index 89791ea..06704d8 100644
--- a/log4k/src/commonMain/kotlin/saschpe/log4k/Log.kt
+++ b/log4k/src/commonMain/kotlin/saschpe/log4k/Log.kt
@@ -9,6 +9,14 @@ import kotlin.native.concurrent.ThreadLocal
 object Log {
     enum class Level { Verbose, Debug, Info, Warning, Error, Assert }
 
+    /**
+     * List of logging "backends" to use, defaults to a [ConsoleLogger].
+     *
+     * You can add additional (custom) loggers, like a [FileLogger] with default parameters:
+     * ```kotlin
+     * Log.loggers += FileLogger()
+     * ```
+     */
     @JvmField
     val loggers = mutableListOf<Logger>(ConsoleLogger())
 
@@ -86,5 +94,14 @@ object Log {
         loggers.forEach { it.log(priority, tag, message, throwable) }
 }
 
-fun Any.logged(level: Log.Level = Log.Level.Debug) =
-    apply { Log.log(level, message = toString(), tag = this::class.simpleName ?: "") }
+/**
+ * Log any Kotlin object, like:
+ *
+ * ```kotlin
+ * list(1,2,3).logged()
+ * mapOf("left" to "right").logged()
+ * Pair("Log4k", "rocks!").logged()
+ * ```
+ */
+inline fun <reified T : Any> T.logged(level: Log.Level = Log.Level.Debug): T =
+    apply { Log.log(level, message = toString(), tag = T::class.simpleName ?: "") }
diff --git a/log4k/src/commonTest/kotlin/saschpe/log4k/LoggedTest.kt b/log4k/src/commonTest/kotlin/saschpe/log4k/LoggedTest.kt
index 4e55ee4..a833a89 100644
--- a/log4k/src/commonTest/kotlin/saschpe/log4k/LoggedTest.kt
+++ b/log4k/src/commonTest/kotlin/saschpe/log4k/LoggedTest.kt
@@ -2,6 +2,7 @@ package saschpe.log4k
 
 import testing.TestLoggerTest
 import kotlin.test.Test
+import kotlin.test.assertEquals
 
 internal expect val expectedListTag: String
 internal expect val expectedMapTag: String
@@ -25,10 +26,11 @@ class LoggedTest : TestLoggerTest() {
         val list = listOf("Hello", "World")
 
         // Act
-        list.logged()
+        val returned: List<String> = list.logged()
 
         // Assert
-        assertTestLogger(Log.Level.Debug, "[Hello, World]", expectedListTag, null)
+        assertTestLogger(Log.Level.Debug, "[Hello, World]", "List", null)
+        assertEquals(list, returned)
     }
 
     @Test
@@ -40,6 +42,6 @@ class LoggedTest : TestLoggerTest() {
         map.logged()
 
         // Assert
-        assertTestLogger(Log.Level.Debug, "{Hello=World}", expectedMapTag, null)
+        assertTestLogger(Log.Level.Debug, "{Hello=World}", "Map", null)
     }
 }