docs(log): document warn module (#5973)

_tools/check_docs.ts

@@ -70,6 +70,7 @@ const ENTRY_POINTS = [
   "../io/mod.ts",
   "../json/mod.ts",
   "../jsonc/mod.ts",
+  "../log/warn.ts",
   "../media_types/mod.ts",
   "../msgpack/mod.ts",
   "../net/mod.ts",

log/logger.ts

@@ -4,6 +4,7 @@ import { getLevelByName, getLevelName, LogLevels } from "./levels.ts";
 import type { LevelName, LogLevel } from "./levels.ts";
 import type { BaseHandler } from "./base_handler.ts";
 
+/** Any function that can be called with any arguments and return any value. */
 // deno-lint-ignore no-explicit-any
 export type GenericFunction = (...args: any[]) => any;
 

log/warn.ts

@@ -4,8 +4,55 @@
 import { getLogger } from "./get_logger.ts";
 import type { GenericFunction } from "./logger.ts";
 
-/** Log with warning level, using default logger. */
+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}.
+ *
+ * @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 { warn } from "@std/log/warn";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(warn("This is a warning message."), "This is a warning message.");
+ * // Prints: "WARN This is a warning message."
+ *
+ * assertEquals(warn(() => "This is a warning message."), "This is a warning message.");
+ * // Prints: "WARN This is a warning message."
+ * ```
+ */
 export function warn<T>(msg: () => T, ...args: unknown[]): T | undefined;
+/**
+ * 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}.
+ *
+ * @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 { warn } from "@std/log/warn";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(warn("This is a warning message."), "This is a warning message.");
+ * // Prints: "WARN This is a warning message."
+ *
+ * assertEquals(warn(() => "This is a warning message."), "This is a warning message.");
+ * // Prints: "WARN This is a warning message."
+ * ```
+ */
 export function warn<T>(
   msg: T extends GenericFunction ? never : T,
   ...args: unknown[]