docs(log): document pass-through functions

_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",

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<T>(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<T>(
   msg: T extends GenericFunction ? never : T,
   ...args: unknown[]

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<T>(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<T>(
   msg: T extends GenericFunction ? never : T,
   ...args: unknown[]

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<T>(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<T>(
   msg: T extends GenericFunction ? never : T,
   ...args: unknown[]

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<T>(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<T>(
   msg: T extends GenericFunction ? never : T,
   ...args: unknown[]

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.