migrate kslog docs

docs/kslog/index.md

@@ -0,0 +1,3 @@
+# KSLog
+
+[KSLog](https://github.com/InsanusMokrassar/kslog) is a simple multiplatform tool for native logging.

docs/kslog/logging.md

@@ -0,0 +1,126 @@
+# Logging
+
+> NOTE: **Message type notice**
+> On this page all the messages will be just simple `String`, but you may pass any object as the message
+
+As has been said in the [setup](setup.md) section, this library contains next levels of logging with their default representations on each platform:
+
+| Weight (by order) | LogLevel name | JS | JVM Loggers | Android |
+| -: | :- | :- | :- | :- |
+| 0 | DEBUG   | console.log | Level.FINEST | Log.d |
+| 1 | VERBOSE | console.info | Level.FINE | Log.v |
+| 2 | INFO    | console.info | Level.INFO | Log.i |
+| 3 | WARNING | console.warn | Level.WARNING | Log.w |
+| 4 | ERROR   | console.error | Level.SEVERE | Log.e |
+| 5 | ASSERT  | console.error | Level.SEVERE | Log.wtf |
+
+Each of these levels have fullname and shortname shortcat extensions:
+
+* `KSLog.debug`/`KSLog.d`/`KSLog.dS`
+* `KSLog.verbose`/`KSLog.v`/`KSLog.vS`
+* `KSLog.info`/`KSLog.i`/`KSLog.iS`
+* `KSLog.warning`/`KSLog.w`/`KSLog.wS`
+* `KSLog.error`/`KSLog.e`/`KSLog.eS`
+* `KSLog.assert`/`KSLog.wtf`/`KSLog.wtfS`
+
+And any of these shortcuts may accept one of several arguments combinations:
+
+* Tag (Optional), Throwable (Optional), Message Builder (simple inline callback for lazy creating of log message). This type of arguments is duplicated with `S` suffix for `suspendable` messages creating, for example
+* Message, Throwable (Optional)
+* Tag, Message, Throwable (Optional)
+
+So, when you want to log some expected exception, there are three common ways to do it:
+
+```kotlin
+val logger = KSLog.default
+
+// with callback
+logger.info(tag, throwable) {
+  "Some your message for this event"
+}
+
+// with suspendable callback
+logger.infoS(tag, throwable) {
+  withContext(Dispatchers.Default) {
+    "Some your message for this event"
+  }
+}
+
+// Just with message
+logger.info("Some your message for this event", throwable)
+
+// With message and tag as strings
+logger.info(tag, "Some your message for this event", throwable)
+```
+
+Of course, any of this calls can be shortenned:
+
+```kotlin
+val logger = KSLog.default
+
+// with callback
+logger.i(tag, throwable) {
+  "Some your message for this event"
+}
+
+// with suspendable callback
+logger.iS(tag, throwable) {
+  withContext(Dispatchers.Default) {
+    "Some your message for this event"
+  }
+}
+
+// Just with message
+logger.i("Some your message for this event", throwable)
+
+// With message and tag as strings
+logger.i(tag, "Some your message for this event", throwable)
+```
+
+There is special shortcat - for base `performLog`. In that case the only change is that you will require to pass the `LogLevel` more obviously:
+
+```kotlin
+val logger = KSLog.default
+
+// with callback
+logger.log(LogLevel.INFO, tag, throwable) {
+  "Some your message for this event"
+}
+
+// with suspendable callback
+logger.logS(LogLevel.INFO, tag, throwable) {
+  withContext(Dispatchers.Default) {
+    "Some your message for this event"
+  }
+}
+
+// Just with message
+logger.log(LogLevel.INFO, "Some your message for this event", throwable)
+
+// With message and tag as strings
+logger.log(LogLevel.INFO, tag, "Some your message for this event", throwable)
+```
+
+OR
+
+```kotlin
+val logger = KSLog.default
+
+// with callback
+logger.l(LogLevel.INFO, tag, throwable) {
+  "Some your message for this event"
+}
+
+// with suspendable callback
+logger.lS(LogLevel.INFO, tag, throwable) {
+  withContext(Dispatchers.Default) {
+    "Some your message for this event"
+  }
+}
+
+// Just with message
+logger.l(LogLevel.INFO, "Some your message for this event", throwable)
+
+// With message and tag as strings
+logger.l(LogLevel.INFO, tag, "Some your message for this event", throwable)
+```

docs/kslog/setup.md

@@ -0,0 +1,153 @@
+# Setup
+
+## Dependency installation
+
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/kslog/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/kslog)
+
+### Gradle (Groovy)
+
+```groovy
+implementation "dev.inmo:kslog:$kslog_version"
+```
+
+### Gradle (Kotlin Script)
+
+```kotlin
+implementation("dev.inmo:kslog:$kslog_version")
+```
+
+### Maven (pom)
+
+```xml
+<dependency>
+  <groupId>dev.inmo</groupId>
+  <artifactId>kslog</artifactId>
+  <version>${kslog_version}</version>
+</dependency>
+```
+
+## Setup in code
+
+The main point in setup in your code is to setup default logger:
+
+```kotlin
+KSLog.default = KSLog("defaultTag")
+```
+
+You may use custom `messageFormatter` in any of `KSLog` factory to customize output of `KSLog` logging. For example:
+
+```kotlin
+KSLog(
+  "loggingWithCustomFormat",
+  messageFormatter = { level, tag, message, throwable ->
+    println("[$level] $tag - $message: $throwable")
+  }
+)
+```
+
+Additionally you may use one of several different settings:
+
+* `minLoggingLevel` - minimal logging level for the log which will be logged. The order of log level is next:
+  * DEBUG
+  * VERBOSE
+  * INFO
+  * WARNING
+  * ERROR
+  * ASSERT
+* `levels` - and iterable with the levels which should be logged
+* `firstLevel`,`secondLevel`,`otherLevels` - as `levels`, but `vararg` :)
+
+In case you are passing `minLoggingLevel`, the **level and more important levels** will be passed to logs. For example, when you are settings up your logger as in next snippet:
+
+```kotlin
+val logger = KSLog(
+    "exampleTag",
+    minLoggingLevel = LogLevel.INFO
+)
+```
+
+The next levels will be logged with `logger`:
+
+* `INFO`
+* `WARNING`
+* `ERROR`
+* `ASSERT`
+
+## Special loggers
+
+### CallbackKSLog
+
+It is logger which will call incoming `performLogCallback` on each logging. This logger can be create simply with one callback:
+
+```kotlin
+KSLog { level, tag, message, throwable ->
+  println("[$level] $tag - $message: $throwable")
+}
+```
+
+### TagLogger
+
+It is simple value class which can be used for zero-cost usage of some tag and calling for `KSLog.default`. For example, if you will create tag logger with next code:
+
+```kotlin
+val logger = TagLogger("tagLoggerTag")
+```
+
+The `logger` will call `KSLog.default` with the tag `tagLoggerTag` on each calling of logging.
+
+### FilterKSLog
+
+This pretty simple logger will call its `fallbackLogger` only in cases when incoming `messageFilter` will return true for logging:
+
+```kotlin
+val baseLogger = KSLog("base") // log everything with the tag `base` if not set other
+val filtered = baseLogger.filtered { _, t, _ ->
+    t == "base"
+}
+```
+
+In the example above `baseLogger` will perform logs in two ways: when it has been called directly or when we call log performing with the tag `"base"` or `null`. Besides, you can see there extension `filtered` which allow to create `FilterKSLog` logger with simple lambda.
+
+### TypedKSLog
+
+This logger accepts map of types with the target loggers. You may build this logger with the special simple DSL:
+
+```kotlin
+val baseLogger = KSLog("base") // log everything with the tag `base` if not set other
+val typed = buildTypedLogger {
+  on<Int>(baseLogger) // log all ints to the baseLogger
+  on<Float> { _, _, message, _ ->// log all floats to the passed logger
+  	println(message.toString()) // just print all floats
+  }
+  default { level, tag, message, throwable ->
+    KSLog.performLog(level, tag, message, throwable)
+  }
+}
+```
+
+### Automatical loggers
+
+There are two things which can be useful in your code: `logger` and `logTag` extensions. `logTag` is the autocalculated by your object classname tag. `logger` extension can be used with applying to any object like in the next snippet:
+
+```kotlin
+class SomeClass {
+  init {
+    logger.i("inited")
+  }
+}
+```
+
+The code above will trigger calling of logging in `KSLog.default` with level `LogLevel.INFO` using tag `SomeClass` and message `"inited"`. As you could have guessed, `logger` is using `TagLogger` with `logTag` underhood and the most expensive operation here is automatical calculation of `logTag`.
+
+* Extension `logger`
+
+## JVM specific setup
+
+For JVM you may setup additionally use java loggers as the second parameter of `KSLog` factory. For example:
+
+```kotlin
+KSLog(
+  "yourTag"
+  Logger.getLogger("YourJavaLoggerName")
+)
+```

mkdocs.yml

@@ -29,6 +29,10 @@ nav:
         - Describing:
             - 'krontab/describing/string-format.md'
             - 'krontab/describing/krontabscheduler.md'
+    - 'KSLog':
+        - 'kslog/index.md'
+        - 'kslog/setup.md'
+        - 'kslog/logging.md'
 
 use_directory_urls: false