docs(log): document getLogger() and Logger

_tools/check_docs.ts

@@ -77,6 +77,7 @@ const ENTRY_POINTS = [
   "../log/error.ts",
   "../log/info.ts",
   "../log/formatters.ts",
+  "../log/get_logger.ts",
   "../media_types/mod.ts",
   "../msgpack/mod.ts",
   "../net/mod.ts",

log/get_logger.ts

@@ -4,7 +4,62 @@
 import { Logger } from "./logger.ts";
 import { state } from "./_state.ts";
 
-/** Get a logger instance. If not specified `name`, get the default logger. */
+export type { Logger };
+
+/**
+ * Get a logger instance. If not specified `name`, get the default logger.
+ *
+ * @param name The name of the logger.
+ * @returns The logger instance.
+ *
+ * @example Usage (without defined name and minimal setup)
+ * ```ts
+ * import { getLogger } from "@std/log/get-logger";
+ * import "@std/log/setup";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const logger = getLogger();
+ * const result = logger.info("Hello world!"); // Prints "INFO Hello world!" in blue
+ *
+ * assertEquals(result, "Hello world!");
+ * ```
+ *
+ * @example Usage (without defined name and custom setup)
+ * ```ts
+ * import { getLogger } from "@std/log/get-logger";
+ * import { setup } from "@std/log/setup";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * setup({
+ *   handlers: {
+ *     console: new ConsoleHandler("DEBUG"),
+ *   },
+ *   loggers: {
+ *     default: {
+ *       level: "DEBUG",
+ *       handlers: ["console"],
+ *     },
+ *   },
+ * });
+ *
+ * const logger = getLogger();
+ *
+ * const result = logger.info("Hello world!"); // Prints "INFO Hello world!" in blue
+ *
+ * assertEquals(result, "Hello world!");
+ * ```
+ *
+ * @example Usage (with defined name)
+ * ```ts
+ * import { getLogger } from "@std/log/get-logger";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const logger = getLogger("my-logger");
+ * const result = logger.info("Hello world!");
+ *
+ * assertEquals(result, "Hello world!");
+ * ```
+ */
 export function getLogger(name?: string): Logger {
   if (!name) {
     const d = state.loggers.get("default");

log/logger.ts

@@ -220,15 +220,39 @@ export class LogRecord {
   }
 }
 
+/** Options for {@linkcode Logger}. */
 export interface LoggerOptions {
+  /** The handlers to use for the logger. */
   handlers?: BaseHandler[];
 }
 
+/**
+ * A logger that can log messages at different levels.
+ *
+ * @example Usage
+ * ```ts
+ * import { Logger } from "@std/log/logger";
+ * import { LogLevels } from "@std/log/levels";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const logger = new Logger("example", LogLevels.INFO);
+ * const result = logger.info("Hello, world!");
+ *
+ * assertEquals(result, "Hello, world!");
+ * ```
+ */
 export class Logger {
   #level: LogLevel;
   handlers: BaseHandler[];
   readonly #loggerName: string;
 
+  /**
+   * Constructs a new instance.
+   *
+   * @param loggerName The name of the logger.
+   * @param levelName The name of the log level.
+   * @param options The options to create a new logger.
+   */
   constructor(
     loggerName: string,
     levelName: LevelName,
@@ -239,12 +263,42 @@ export class Logger {
     this.handlers = options.handlers ?? [];
   }
 
-  /** Use this to retrieve the current numeric log level. */
+  /**
+   * Getter for the log level.
+   *
+   * @returns The log level.
+   *
+   * @example Usage
+   * ```ts
+   * import { Logger } from "@std/log/logger";
+   * import { LogLevels } from "@std/log/levels";
+   * import { assertEquals } from "@std/assert/equals";
+   *
+   * const logger = new Logger("example", LogLevels.INFO);
+   * assertEquals(logger.level, LogLevels.INFO);
+   * ```
+   */
   get level(): LogLevel {
     return this.#level;
   }
 
-  /** Use this to set the numeric log level. */
+  /**
+   * Setter for the log level.
+   *
+   * @param level The log level to set.
+   *
+   * @example Usage
+   * ```ts
+   * import { Logger } from "@std/log/logger";
+   * import { LogLevels } from "@std/log/levels";
+   * import { assertEquals } from "@std/assert/equals";
+   *
+   * const logger = new Logger("example", LogLevels.INFO);
+   * logger.level = LogLevels.DEBUG;
+   *
+   * assertEquals(logger.level, LogLevels.DEBUG);
+   * ```
+   */
   set level(level: LogLevel) {
     try {
       this.#level = getLevelByName(getLevelName(level));
@@ -253,13 +307,62 @@ export class Logger {
     }
   }
 
+  /**
+   * Getter for the name of the log level.
+   *
+   * @returns The name of the log level.
+   *
+   * @example Usage
+   * ```ts
+   * import { Logger } from "@std/log/logger";
+   * import { LogLevels } from "@std/log/levels";
+   * import { assertEquals } from "@std/assert/equals";
+   *
+   * const logger = new Logger("example", LogLevels.INFO);
+   * assertEquals(logger.levelName, "INFO");
+   * ```
+   */
   get levelName(): LevelName {
     return getLevelName(this.#level);
   }
+
+  /**
+   * Setter for the name of the log level.
+   *
+   * @param levelName The name of the log level to set.
+   *
+   * @example Usage
+   * ```ts
+   * import { Logger } from "@std/log/logger";
+   * import { LogLevels } from "@std/log/levels";
+   * import { assertEquals } from "@std/assert/equals";
+   *
+   * const logger = new Logger("example", LogLevels.INFO);
+   * logger.levelName = "DEBUG";
+   *
+   * assertEquals(logger.level, LogLevels.DEBUG);
+   * ```
+   */
   set levelName(levelName: LevelName) {
     this.#level = getLevelByName(levelName);
   }
 
+  /**
+   * Getter for the name of the logger.
+   *
+   * @returns The name of the logger.
+   *
+   * @example Usage
+   * ```ts
+   * import { Logger } from "@std/log/logger";
+   * import { LogLevels } from "@std/log/levels";
+   * import { assertEquals } from "@std/assert/equals";
+   *
+   * const logger = new Logger("example", LogLevels.INFO);
+   *
+   * assertEquals(logger.loggerName, "example");
+   * ```
+   */
   get loggerName(): string {
     return this.#loggerName;
   }