Merge pull request #439 from MohamedHarmoush/documentation/logging

Add documentation for `logging` package in `hexagon_core` module (issue #271)

hexagon_core/src/main/kotlin/logging/Logger.kt

@@ -32,47 +32,107 @@ class Logger(val name: String) {
     constructor(type: KClass<*>):
         this(type.qualifiedName ?: error("Cannot get qualified name of $type"))
 
+    /**
+     *  Log a message using [TRACE][TRACE] level.
+     *
+     * @param [message] The required message to log.
+     */
     fun trace(message: () -> Any?) {
         log.log(TRACE, message)
     }
 
+    /**
+     *  Log a message using [DEBUG][DEBUG] level.
+     *
+     * @param [message] The required message to log.
+     */
     fun debug(message: () -> Any?) {
         log.log(DEBUG, message)
     }
 
+    /**
+     *  Log a message using [INFO][INFO] level.
+     *
+     * @param [message] The required message to log.
+     */
     fun info(message: () -> Any?) {
         log.log(INFO, message)
     }
 
+    /**
+     *  Log a message using [WARN][WARN] level.
+     *
+     * @param [message] The required message to log.
+     */
     fun warn(message: () -> Any?) {
         log.log(WARN, message)
     }
 
+    /**
+     *  Log a message using [ERROR][ERROR] level.
+     *
+     * @param [message] The required message to log.
+     */
     fun error(message: () -> Any?) {
         log.log(ERROR, message)
     }
 
+    /**
+     *  Log a message using [WARN][WARN] level with associated exception information.
+     *
+     * @param [exception] The exception associated with log message.
+     * @param [message] The required message to log.
+     */
     fun <E : Throwable> warn(exception: E, message: (E) -> Any?) {
         log.log(WARN, exception, message)
     }
 
+    /**
+     *  Log a message using [ERROR][ERROR] level with associated exception information.
+     *
+     * @param [exception] The exception associated with log message.
+     * @param [message] The required message to log.
+     */
     fun <E : Throwable> error(exception: E, message: (E) -> Any?) {
         log.log(ERROR, exception, message)
     }
 
+    /**
+     *  Log a message using [TRACE][TRACE] level.
+     *
+     * @param [message] The required message to log.
+     */
     fun flare(message: () -> Any? = { "" }) {
         log.log(TRACE) { "$BOLD$BLINK$FLARE_PREFIX$RESET ${message()}" }
     }
 
+    /**
+     *  Log a message using [TRACE][TRACE] level with the logging time.
+     *
+     * @param [startNanos] The start logging time in nanoseconds.
+     * @param [message] The required message to log.
+     */
     fun time(startNanos: Long, message: () -> Any? = { "" }) {
         log.log(TRACE) { "${message() ?: "TIME"} : ${formatNanos(nanoTime() - startNanos)}" }
     }
 
+    /**
+     *  Execute a lambda block and log a message using [TRACE][TRACE] level with the logging time.
+     *
+     * @param [message] The required message to log.
+     * @param [block] The lambda block to execute.
+     */
     fun <T> time(message: () -> Any? = { null }, block: () -> T): T {
         val start = nanoTime()
         return block().also { time(start, message) }
     }
 
+    /**
+     *  Execute a lambda block and log a message using [TRACE][TRACE] level with the logging time.
+     *
+     * @param [message] The required message to log.
+     * @param [block] The lambda block to execute.
+     */
     fun <T> time(message: Any?, block: () -> T): T = this.time({ message }, block)
 
     private fun formatNanos (nanoseconds: Long): String = "%1.3f ms".format (nanoseconds / 1e6)

hexagon_core/src/main/kotlin/logging/LoggerPort.kt

@@ -1,8 +1,28 @@
 package com.hexagonkt.logging
 
+/**
+ * A Logger is used to log messages for a specific system or application component.
+ */
 interface LoggerPort {
 
+    /**
+     * Log a message, with associated exception information.
+     *
+     * @param [level] One of the message level identifiers, e.g., TRACE.
+     * @param [exception] The exception associated with log message.
+     * @param [message] The required message to log.
+     *
+     * @see [LoggingLevel]
+     */
     fun <E : Throwable> log(level: LoggingLevel, exception: E, message: (E) -> Any?)
 
+    /**
+     *  Log a message
+     *
+     * @param [level] One of the message level identifiers, e.g., TRACE.
+     * @param [message] The required message to log.
+     *
+     * @see  [LoggingLevel]
+     */
     fun log(level: LoggingLevel, message: () -> Any?)
 }

hexagon_core/src/main/kotlin/logging/Logging.kt

@@ -1,10 +1,11 @@
 package com.hexagonkt.logging
 
+
 /** Default logger for when you feel too lazy to declare one. */
 val logger: Logger by lazy { Logger(Logger::class) }
 
 /**
- * [TODO](https://github.com/hexagonkt/hexagon/issues/271).
+ * Uses this [T] to log a message with a prefix using [TRACE][LoggingLevel.TRACE] level.
  *
  * com.hexagonkt.logging.Logger must have TRACE level
  *
@@ -18,7 +19,7 @@ fun <T> T.trace(prefix: String = ""): T =
     apply { logger.trace { "$prefix$this" } }
 
 /**
- * [TODO](https://github.com/hexagonkt/hexagon/issues/271).
+ * Uses this [T] to log a message with a prefix using [DEBUG][LoggingLevel.DEBUG] level.
  *
  * com.hexagonkt.logging.Logger must have DEBUG level
  *
@@ -32,7 +33,7 @@ fun <T> T.debug(prefix: String = ""): T =
     apply { logger.debug { "$prefix$this" } }
 
 /**
- * [TODO](https://github.com/hexagonkt/hexagon/issues/271).
+ * Uses this [T] to log a message with a prefix using [INFO][LoggingLevel.INFO] level.
  *
  * com.hexagonkt.logging.Logger must have INFO level
  *

hexagon_core/src/main/kotlin/logging/LoggingLevel.kt

@@ -1,5 +1,14 @@
 package com.hexagonkt.logging
 
+/**
+ * Logger logging level values:
+ * - [TRACE][LoggingLevel.TRACE].
+ * - [DEBUG][LoggingLevel.DEBUG].
+ * - [INFO][LoggingLevel.INFO].
+ * - [WARN][LoggingLevel.WARN].
+ * - [ERROR][LoggingLevel.ERROR].
+ * - [OFF][LoggingLevel.OFF].
+ */
 enum class LoggingLevel {
     TRACE,
     DEBUG,

hexagon_core/src/main/kotlin/logging/LoggingManager.kt

@@ -5,23 +5,50 @@ import com.hexagonkt.logging.jul.JulLoggingAdapter
 import kotlin.reflect.KClass
 
 /**
- * [TODO](https://github.com/hexagonkt/hexagon/issues/271).
+ * Manages Logs using [JulLoggingAdapter]
  */
 object LoggingManager {
     var adapter: LoggingPort = JulLoggingAdapter
 
+    /**
+     * Set a logger logging level by name.
+     *
+     * @param [name] Logger name.
+     * @param [level] One of the logging levels identifiers, e.g., TRACE
+     * @see [LoggingLevel]
+     */
     fun setLoggerLevel(name: String, level: LoggingLevel) {
         adapter.setLoggerLevel(name, level)
     }
 
+    /**
+     * Set a logging level for a logger with a class instance.
+     *
+     * @param [instance] class instance.
+     * @param [level] One of the logging levels identifiers, e.g., TRACE
+     * @see [LoggingLevel]
+     */
     fun setLoggerLevel(instance: Any, level: LoggingLevel) {
         setLoggerLevel(instance::class, level)
     }
 
+    /**
+     * Set a logging level for a logger with a class name.
+     *
+     * @param [type] Class type.
+     * @param [level] One of the logging levels identifiers, e.g., TRACE
+     * @see [LoggingLevel]
+     */
     fun setLoggerLevel(type: KClass<*>, level: LoggingLevel) {
         setLoggerLevel(type.qualifiedName ?: fail, level)
     }
 
+    /**
+     * Set a logger logging level for a logger with a default name.
+     *
+     * @param [level] One of the logging levels identifiers, e.g., TRACE
+     * @see [LoggingLevel]
+     */
     fun setLoggerLevel(level: LoggingLevel) {
         setLoggerLevel("", level)
     }

hexagon_core/src/main/kotlin/logging/LoggingPort.kt

@@ -1,8 +1,26 @@
 package com.hexagonkt.logging
 
+/**
+ * Logging Contract for:
+ * - Creating logger [createLogger].
+ * - Setting the logging level [setLoggerLevel].
+ */
 interface LoggingPort {
 
+    /**
+     * Creates [LoggerPort] by name.
+     *
+     * @param [name] Logger name.
+     */
     fun createLogger(name: String): LoggerPort
 
+    /**
+     * Indicates logging level of a logger.
+     *
+     * @param [name] Logger name.
+     * @param [level] One of the logging levels identifiers, e.g., TRACE
+     *
+     * @see [LoggingLevel]
+     */
     fun setLoggerLevel(name: String, level: LoggingLevel)
 }

hexagon_core/src/main/kotlin/logging/jul/JulLoggingAdapter.kt

@@ -12,6 +12,9 @@ import com.hexagonkt.logging.LoggingPort
 import java.util.logging.Level
 import java.util.logging.Logger as JulLogger
 
+/**
+ * Implements  [LoggingPort] using [Logger][JulLogger].
+ */
 object JulLoggingAdapter : LoggingPort {
 
     init {

hexagon_core/src/main/kotlin/logging/jul/PatternFormat.kt

@@ -17,6 +17,11 @@ import java.util.logging.Formatter
 import java.util.logging.Level
 import java.util.logging.LogRecord
 
+/**
+ * A Formatter implements [Formatter] provides support for formatting Logs.
+ *
+ * @property [useColor] use a color to log messages.
+ */
 class PatternFormat(private val useColor: Boolean = true) : Formatter() {
 
     private companion object {

hexagon_core/src/main/kotlin/logging/jul/SystemOutHandler.kt

@@ -5,6 +5,11 @@ import java.util.logging.Level
 import java.util.logging.LogRecord
 import java.util.logging.StreamHandler
 
+/**
+ *  Create a StreamHandler with a given [Formatter].
+ *
+ *  @property [Formatter] Formatter with a default value PatternFormatter object.
+ */
 class SystemOutHandler(handlerFormatter: Formatter = PatternFormat()) : StreamHandler() {
 
     override fun publish(record: LogRecord) {