From 999eaa8b9b79a1590429d317e26f1bca6d5228ca Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Tue, 1 Oct 2024 13:47:20 +1000 Subject: [PATCH] docs(log): document `getLogger()` and `Logger` --- _tools/check_docs.ts | 1 + log/get_logger.ts | 57 ++++++++++++++++++++++- log/logger.ts | 107 ++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 162 insertions(+), 3 deletions(-) diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index da8439906..dc4a0b698 100644 --- a/_tools/check_docs.ts +++ b/_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", diff --git a/log/get_logger.ts b/log/get_logger.ts index 98df3dfeb..ef106d327 100644 --- a/log/get_logger.ts +++ b/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"); diff --git a/log/logger.ts b/log/logger.ts index cc9fd65c4..5bf17e39c 100644 --- a/log/logger.ts +++ b/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; }