From e09253473123faee71f616a2774de093a613f9a1 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Fri, 27 Sep 2024 09:41:22 +1000 Subject: [PATCH] docs(log): document pass-through functions --- _tools/check_docs.ts | 4 ++ log/critical.ts | 49 ++++++++++++++++++++- log/debug.ts | 101 ++++++++++++++++++++++++++++++++++++++++++- log/error.ts | 49 ++++++++++++++++++++- log/info.ts | 49 ++++++++++++++++++++- log/warn.ts | 3 +- 6 files changed, 250 insertions(+), 5 deletions(-) diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index c20e7ac5e592..ce48d879a1de 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -71,6 +71,10 @@ const ENTRY_POINTS = [ "../json/mod.ts", "../jsonc/mod.ts", "../log/warn.ts", + "../log/critical.ts", + "../log/debug.ts", + "../log/error.ts", + "../log/info.ts", "../media_types/mod.ts", "../msgpack/mod.ts", "../net/mod.ts", diff --git a/log/critical.ts b/log/critical.ts index 62c772f9a7b0..8e8e54f6a362 100644 --- a/log/critical.ts +++ b/log/critical.ts @@ -4,8 +4,55 @@ import { getLogger } from "./get_logger.ts"; import type { GenericFunction } from "./logger.ts"; -/** Log with critical level, using default logger. */ +/** + * Log at the critical level. + * + * This function is a pass-through to the default logger's `critical` method. By + * default, the default logger is configured to use {@linkcode console.log} and + * print in bold red text. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { critical } from "@std/log/critical"; + * import { assertEquals } from "@std/assert/equals"; + * + * assertEquals(critical("This is a critical message."), "This is a critical message."); + * // Prints: "CRITICAL This is a critical message." + * + * assertEquals(critical(() => "This is a critical message."), "This is a critical message."); + * // Prints: "CRITICAL This is a critical message." + * ``` + */ export function critical(msg: () => T, ...args: unknown[]): T | undefined; +/** + * Log at the critical level. + * + * This function is a pass-through to the default logger's `critical` method. By + * default, the default logger is configured to use {@linkcode console.log} and + * print in bold red text. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { critical } from "@std/log/critical"; + * import { assertEquals } from "@std/assert/equals"; + * + * assertEquals(critical("This is a critical message."), "This is a critical message."); + * // Prints: "CRITICAL This is a critical message." + * + * assertEquals(critical(() => "This is a critical message."), "This is a critical message."); + * // Prints: "CRITICAL This is a critical message." + * ``` + */ export function critical( msg: T extends GenericFunction ? never : T, ...args: unknown[] diff --git a/log/debug.ts b/log/debug.ts index 0c6d6663d54b..80fa16cb4db9 100644 --- a/log/debug.ts +++ b/log/debug.ts @@ -4,8 +4,107 @@ import { getLogger } from "./get_logger.ts"; import type { GenericFunction } from "./logger.ts"; -/** Log with debug level, using default logger. */ +/** + * Log at the debug level. + * + * This function is a pass-through to the default logger's `debug` method. By + * default, this function is a no-op. To enable debug logging, set call + * {@linkcode https://jsr.io/@std/log/doc/setup/~/setup | setup} and set the + * default level to `DEBUG`. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage without setup + * ```ts + * import { debug } from "@std/log/debug"; + * import { assertEquals } from "@std/assert/equals"; + * + * assertEquals(debug("This is a debug message."), "This is a debug message."); + * // Prints: "" + * + * assertEquals(debug(() => "This is a debug message."), "This is a debug message."); + * // Prints: "" + * ``` + * + * @example Usage with setup + * ```ts + * import { ConsoleHandler, debug, setup } from "@std/log"; + * import { assertEquals } from "@std/assert/equals"; + * + * setup({ + * handlers: { + * default: new ConsoleHandler("DEBUG"), + * }, + * loggers: { + * default: { + * level: "DEBUG", + * handlers: ["default"], + * }, + * }, + * }); + * + * assertEquals(debug("This is a debug message."), "This is a debug message."); + * + * assertEquals( + * debug(() => "This is a debug message."), + * "This is a debug message.", + * ); + * ``` + */ export function debug(msg: () => T, ...args: unknown[]): T | undefined; +/** + * Log at the debug level. + * + * This function is a pass-through to the default logger's `debug` method. By + * default, this function is a no-op. To enable debug logging, set call + * {@linkcode https://jsr.io/@std/log/doc/setup/~/setup | setup} and set the + * default level to `DEBUG`. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage without setup + * ```ts + * import { debug } from "@std/log/debug"; + * import { assertEquals } from "@std/assert/equals"; + * + * assertEquals(debug("This is a debug message."), "This is a debug message."); + * // Prints: "" + * + * assertEquals(debug(() => "This is a debug message."), "This is a debug message."); + * // Prints: "" + * ``` + * + * @example Usage with setup + * ```ts + * import { ConsoleHandler, debug, setup } from "@std/log"; + * import { assertEquals } from "@std/assert/equals"; + * + * setup({ + * handlers: { + * default: new ConsoleHandler("DEBUG"), + * }, + * loggers: { + * default: { + * level: "DEBUG", + * handlers: ["default"], + * }, + * }, + * }); + * + * assertEquals(debug("This is a debug message."), "This is a debug message."); + * + * assertEquals( + * debug(() => "This is a debug message."), + * "This is a debug message.", + * ); + * ``` + */ export function debug( msg: T extends GenericFunction ? never : T, ...args: unknown[] diff --git a/log/error.ts b/log/error.ts index 51aa89102e3a..05696978d9cc 100644 --- a/log/error.ts +++ b/log/error.ts @@ -4,8 +4,55 @@ import { getLogger } from "./get_logger.ts"; import type { GenericFunction } from "./logger.ts"; -/** Log with error level, using default logger. */ +/** + * Log at the error level. + * + * This function is a pass-through to the default logger's `error` method. By + * default, the default logger is configured to use {@linkcode console.log} and + * print in red text. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { error } from "@std/log/error"; + * import { assertEquals } from "@std/assert/equals"; + * + * assertEquals(error("This is an error message."), "This is an error message."); + * // Prints: "ERROR This is an error message." + * + * assertEquals(error(() => "This is an error message."), "This is an error message."); + * // Prints: "ERROR This is an error message." + * ``` + */ export function error(msg: () => T, ...args: unknown[]): T | undefined; +/** + * Log at the error level. + * + * This function is a pass-through to the default logger's `error` method. By + * default, the default logger is configured to use {@linkcode console.log} and + * print in red text. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { error } from "@std/log/error"; + * import { assertEquals } from "@std/assert/equals"; + * + * assertEquals(error("This is an error message."), "This is an error message."); + * // Prints: "ERROR This is an error message." + * + * assertEquals(error(() => "This is an error message."), "This is an error message."); + * // Prints: "ERROR This is an error message." + * ``` + */ export function error( msg: T extends GenericFunction ? never : T, ...args: unknown[] diff --git a/log/info.ts b/log/info.ts index d86405d2c004..1f68065c602b 100644 --- a/log/info.ts +++ b/log/info.ts @@ -4,8 +4,55 @@ import { getLogger } from "./get_logger.ts"; import type { GenericFunction } from "./logger.ts"; -/** Log with info level, using default logger. */ +/** + * Log at the info level. + * + * This function is a pass-through to the default logger's `info` method. By + * default, the default logger is configured to use {@linkcode console.log} and + * print in blue text. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { info } from "@std/log/info"; + * import { assertEquals } from "@std/assert/equals"; + * + * assertEquals(info("This is an info message."), "This is an info message."); + * // Prints: "INFO This is an info message." + * + * assertEquals(info(() => "This is an info message."), "This is an info message."); + * // Prints: "INFO This is an info message." + * ``` + */ export function info(msg: () => T, ...args: unknown[]): T | undefined; +/** + * Log at the info level. + * + * This function is a pass-through to the default logger's `info` method. By + * default, the default logger is configured to use {@linkcode console.log} and + * print in blue text. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { info } from "@std/log/info"; + * import { assertEquals } from "@std/assert/equals"; + * + * assertEquals(info("This is an info message."), "This is an info message."); + * // Prints: "INFO This is an info message." + * + * assertEquals(info(() => "This is an info message."), "This is an info message."); + * // Prints: "INFO This is an info message." + * ``` + */ export function info( msg: T extends GenericFunction ? never : T, ...args: unknown[] diff --git a/log/warn.ts b/log/warn.ts index 95883693ecf4..db5099d024d7 100644 --- a/log/warn.ts +++ b/log/warn.ts @@ -10,7 +10,8 @@ export type { GenericFunction }; * Log at the warning level. * * This function is a pass-through to the default logger's `warn` method. By - * default, the default logger is configured to use {@linkcode console.log}. + * default, the default logger is configured to use {@linkcode console.log} and + * print in yellow text. * * @template T The type of the message to log. * @param msg The message to log.