diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 1307a8817..9a429c917 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -34,6 +34,10 @@ const ENTRY_POINTS = [ "../datetime/mod.ts", "../encoding/mod.ts", "../expect/mod.ts", + "../fmt/bytes.ts", + "../fmt/colors.ts", + "../fmt/duration.ts", + "../fmt/printf.ts", "../front_matter/mod.ts", "../http/mod.ts", "../internal/mod.ts", diff --git a/fmt/bytes.ts b/fmt/bytes.ts index affaa02a1..42b4a8d9a 100644 --- a/fmt/bytes.ts +++ b/fmt/bytes.ts @@ -59,7 +59,7 @@ export interface FormatOptions { * * This module is browser compatible. * - * @example + * @example Usage * ```ts * import { format } from "@std/fmt/bytes"; * @@ -81,6 +81,10 @@ export interface FormatOptions { * format(1337, { locale: "de" }); * //=> '1,34 kB' * ``` + * + * @param num The bytes value to format + * @param options The options for formatting + * @returns The formatted string */ export function format( num: number, diff --git a/fmt/colors.ts b/fmt/colors.ts index bd7d4b7a0..79e9bd7ba 100644 --- a/fmt/colors.ts +++ b/fmt/colors.ts @@ -75,8 +75,24 @@ export interface Rgb { let enabled = !noColor; /** - * Set changing text color to enabled or disabled - * @param value + * Enable or disable text color when styling. + * + * `@std/fmt/colors` automatically detects NO_COLOR environmental variable + * and disables text color. Use this API only when the automatic detection + * doesn't work. + * + * @example Usage + * ```ts + * import { setColorEnabled } from "@std/fmt/colors"; + * + * // Disable text color + * setColorEnabled(false); + * + * // Enable text color + * setColorEnabled(true); + * ``` + * + * @param value The boolean value to enable or disable text color */ export function setColorEnabled(value: boolean) { if (Deno?.noColor) { @@ -86,7 +102,17 @@ export function setColorEnabled(value: boolean) { enabled = value; } -/** Get whether text color change is enabled or disabled. */ +/** + * Get whether text color change is enabled or disabled. + * + * @example Usage + * ```ts + * import { getColorEnabled } from "@std/fmt/colors"; + * + * console.log(getColorEnabled()); // true if enabled, false if disabled + * ``` + * @returns `true` if text color is enabled, `false` otherwise + */ export function getColorEnabled(): boolean { return enabled; } @@ -106,8 +132,8 @@ function code(open: number[], close: number): Code { /** * Applies color and background based on color code and its associated text - * @param str text to apply color settings to - * @param code color code to apply + * @param str The text to apply color settings to + * @param code The color code to apply */ function run(str: string, code: Code): string { return enabled @@ -117,7 +143,16 @@ function run(str: string, code: Code): string { /** * Reset the text modified. - * @param str text to reset + * + * @example Usage + * ```ts + * import { reset } from "@std/fmt/colors"; + * + * console.log(reset("Hello, world!")); + * ``` + * + * @param str The text to reset + * @returns The text with reset color */ export function reset(str: string): string { return run(str, code([0], 0)); @@ -125,7 +160,16 @@ export function reset(str: string): string { /** * Make the text bold. - * @param str text to make bold + * + * @example Usage + * ```ts + * import { bold } from "@std/fmt/colors"; + * + * console.log(bold("Hello, world!")); + * ``` + * + * @param str The text to make bold + * @returns The bold text */ export function bold(str: string): string { return run(str, code([1], 22)); @@ -133,7 +177,16 @@ export function bold(str: string): string { /** * The text emits only a small amount of light. - * @param str text to dim + * + * @example Usage + * ```ts + * import { dim } from "@std/fmt/colors"; + * + * console.log(dim("Hello, world!")); + * ``` + * + * @param str The text to dim + * @returns The dimmed text * * Warning: Not all terminal emulators support `dim`. * For compatibility across all terminals, use {@linkcode gray} or {@linkcode brightBlack} instead. @@ -144,7 +197,16 @@ export function dim(str: string): string { /** * Make the text italic. - * @param str text to make italic + * + * @example Usage + * ```ts + * import { italic } from "@std/fmt/colors"; + * + * console.log(italic("Hello, world!")); + * ``` + * + * @param str The text to make italic + * @returns The italic text */ export function italic(str: string): string { return run(str, code([3], 23)); @@ -152,7 +214,16 @@ export function italic(str: string): string { /** * Make the text underline. - * @param str text to underline + * + * @example Usage + * ```ts + * import { underline } from "@std/fmt/colors"; + * + * console.log(underline("Hello, world!")); + * ``` + * + * @param str The text to underline + * @returns The underlined text */ export function underline(str: string): string { return run(str, code([4], 24)); @@ -160,7 +231,16 @@ export function underline(str: string): string { /** * Invert background color and text color. - * @param str text to invert its color + * + * @example Usage + * ```ts + * import { inverse } from "@std/fmt/colors"; + * + * console.log(inverse("Hello, world!")); + * ``` + * + * @param str The text to invert its color + * @returns The inverted text */ export function inverse(str: string): string { return run(str, code([7], 27)); @@ -168,7 +248,16 @@ export function inverse(str: string): string { /** * Make the text hidden. - * @param str text to hide + * + * @example Usage + * ```ts + * import { hidden } from "@std/fmt/colors"; + * + * console.log(hidden("Hello, world!")); + * ``` + * + * @param str The text to hide + * @returns The hidden text */ export function hidden(str: string): string { return run(str, code([8], 28)); @@ -176,7 +265,16 @@ export function hidden(str: string): string { /** * Put horizontal line through the center of the text. - * @param str text to strike through + * + * @example Usage + * ```ts + * import { strikethrough } from "@std/fmt/colors"; + * + * console.log(strikethrough("Hello, world!")); + * ``` + * + * @param str The text to strike through + * @returns The text with horizontal line through the center */ export function strikethrough(str: string): string { return run(str, code([9], 29)); @@ -184,7 +282,16 @@ export function strikethrough(str: string): string { /** * Set text color to black. - * @param str text to make black + * + * @example Usage + * ```ts + * import { black } from "@std/fmt/colors"; + * + * console.log(black("Hello, world!")); + * ``` + * + * @param str The text to make black + * @returns The black text */ export function black(str: string): string { return run(str, code([30], 39)); @@ -192,7 +299,16 @@ export function black(str: string): string { /** * Set text color to red. - * @param str text to make red + * + * @example Usage + * ```ts + * import { red } from "@std/fmt/colors"; + * + * console.log(red("Hello, world!")); + * ``` + * + * @param str The text to make red + * @returns The red text */ export function red(str: string): string { return run(str, code([31], 39)); @@ -200,7 +316,16 @@ export function red(str: string): string { /** * Set text color to green. - * @param str text to make green + * + * @example Usage + * ```ts + * import { green } from "@std/fmt/colors"; + * + * console.log(green("Hello, world!")); + * ``` + * + * @param str The text to make green + * @returns The green text */ export function green(str: string): string { return run(str, code([32], 39)); @@ -208,7 +333,16 @@ export function green(str: string): string { /** * Set text color to yellow. - * @param str text to make yellow + * + * @example Usage + * ```ts + * import { yellow } from "@std/fmt/colors"; + * + * console.log(yellow("Hello, world!")); + * ``` + * + * @param str The text to make yellow + * @returns The yellow text */ export function yellow(str: string): string { return run(str, code([33], 39)); @@ -216,7 +350,16 @@ export function yellow(str: string): string { /** * Set text color to blue. - * @param str text to make blue + * + * @example Usage + * ```ts + * import { blue } from "@std/fmt/colors"; + * + * console.log(blue("Hello, world!")); + * ``` + * + * @param str The text to make blue + * @returns The blue text */ export function blue(str: string): string { return run(str, code([34], 39)); @@ -224,7 +367,16 @@ export function blue(str: string): string { /** * Set text color to magenta. - * @param str text to make magenta + * + * @example Usage + * ```ts + * import { magenta } from "@std/fmt/colors"; + * + * console.log(magenta("Hello, world!")); + * ``` + * + * @param str The text to make magenta + * @returns The magenta text */ export function magenta(str: string): string { return run(str, code([35], 39)); @@ -232,7 +384,16 @@ export function magenta(str: string): string { /** * Set text color to cyan. - * @param str text to make cyan + * + * @example Usage + * ```ts + * import { cyan } from "@std/fmt/colors"; + * + * console.log(cyan("Hello, world!")); + * ``` + * + * @param str The text to make cyan + * @returns The cyan text */ export function cyan(str: string): string { return run(str, code([36], 39)); @@ -240,7 +401,16 @@ export function cyan(str: string): string { /** * Set text color to white. - * @param str text to make white + * + * @example Usage + * ```ts + * import { white } from "@std/fmt/colors"; + * + * console.log(white("Hello, world!")); + * ``` + * + * @param str The text to make white + * @returns The white text */ export function white(str: string): string { return run(str, code([37], 39)); @@ -248,7 +418,16 @@ export function white(str: string): string { /** * Set text color to gray. - * @param str text to make gray + * + * @example Usage + * ```ts + * import { gray } from "@std/fmt/colors"; + * + * console.log(gray("Hello, world!")); + * ``` + * + * @param str The text to make gray + * @returns The gray text */ export function gray(str: string): string { return brightBlack(str); @@ -256,7 +435,16 @@ export function gray(str: string): string { /** * Set text color to bright black. - * @param str text to make bright-black + * + * @example Usage + * ```ts + * import { brightBlack } from "@std/fmt/colors"; + * + * console.log(brightBlack("Hello, world!")); + * ``` + * + * @param str The text to make bright black + * @returns The bright black text */ export function brightBlack(str: string): string { return run(str, code([90], 39)); @@ -264,7 +452,16 @@ export function brightBlack(str: string): string { /** * Set text color to bright red. - * @param str text to make bright-red + * + * @example Usage + * ```ts + * import { brightRed } from "@std/fmt/colors"; + * + * console.log(brightRed("Hello, world!")); + * ``` + * + * @param str The text to make bright red + * @returns The bright red text */ export function brightRed(str: string): string { return run(str, code([91], 39)); @@ -272,7 +469,16 @@ export function brightRed(str: string): string { /** * Set text color to bright green. - * @param str text to make bright-green + * + * @example Usage + * ```ts + * import { brightGreen } from "@std/fmt/colors"; + * + * console.log(brightGreen("Hello, world!")); + * ``` + * + * @param str The text to make bright green + * @returns The bright green text */ export function brightGreen(str: string): string { return run(str, code([92], 39)); @@ -280,7 +486,16 @@ export function brightGreen(str: string): string { /** * Set text color to bright yellow. - * @param str text to make bright-yellow + * + * @example Usage + * ```ts + * import { brightYellow } from "@std/fmt/colors"; + * + * console.log(brightYellow("Hello, world!")); + * ``` + * + * @param str The text to make bright yellow + * @returns The bright yellow text */ export function brightYellow(str: string): string { return run(str, code([93], 39)); @@ -288,7 +503,16 @@ export function brightYellow(str: string): string { /** * Set text color to bright blue. - * @param str text to make bright-blue + * + * @example Usage + * ```ts + * import { brightBlue } from "@std/fmt/colors"; + * + * console.log(brightBlue("Hello, world!")); + * ``` + * + * @param str The text to make bright blue + * @returns The bright blue text */ export function brightBlue(str: string): string { return run(str, code([94], 39)); @@ -296,7 +520,16 @@ export function brightBlue(str: string): string { /** * Set text color to bright magenta. - * @param str text to make bright-magenta + * + * @example Usage + * ```ts + * import { brightMagenta } from "@std/fmt/colors"; + * + * console.log(brightMagenta("Hello, world!")); + * ``` + * + * @param str The text to make bright magenta + * @returns The bright magenta text */ export function brightMagenta(str: string): string { return run(str, code([95], 39)); @@ -304,7 +537,16 @@ export function brightMagenta(str: string): string { /** * Set text color to bright cyan. - * @param str text to make bright-cyan + * + * @example Usage + * ```ts + * import { brightCyan } from "@std/fmt/colors"; + * + * console.log(brightCyan("Hello, world!")); + * ``` + * + * @param str The text to make bright cyan + * @returns The bright cyan text */ export function brightCyan(str: string): string { return run(str, code([96], 39)); @@ -312,7 +554,16 @@ export function brightCyan(str: string): string { /** * Set text color to bright white. - * @param str text to make bright-white + * + * @example Usage + * ```ts + * import { brightWhite } from "@std/fmt/colors"; + * + * console.log(brightWhite("Hello, world!")); + * ``` + * + * @param str The text to make bright white + * @returns The bright white text */ export function brightWhite(str: string): string { return run(str, code([97], 39)); @@ -320,7 +571,16 @@ export function brightWhite(str: string): string { /** * Set background color to black. - * @param str text to make its background black + * + * @example Usage + * ```ts + * import { bgBlack } from "@std/fmt/colors"; + * + * console.log(bgBlack("Hello, world!")); + * ``` + * + * @param str The text to make its background black + * @returns The text with black background */ export function bgBlack(str: string): string { return run(str, code([40], 49)); @@ -328,7 +588,16 @@ export function bgBlack(str: string): string { /** * Set background color to red. - * @param str text to make its background red + * + * @example Usage + * ```ts + * import { bgRed } from "@std/fmt/colors"; + * + * console.log(bgRed("Hello, world!")); + * ``` + * + * @param str The text to make its background red + * @returns The text with red background */ export function bgRed(str: string): string { return run(str, code([41], 49)); @@ -336,7 +605,16 @@ export function bgRed(str: string): string { /** * Set background color to green. - * @param str text to make its background green + * + * @example Usage + * ```ts + * import { bgGreen } from "@std/fmt/colors"; + * + * console.log(bgGreen("Hello, world!")); + * ``` + * + * @param str The text to make its background green + * @returns The text with green background */ export function bgGreen(str: string): string { return run(str, code([42], 49)); @@ -344,7 +622,16 @@ export function bgGreen(str: string): string { /** * Set background color to yellow. - * @param str text to make its background yellow + * + * @example Usage + * ```ts + * import { bgYellow } from "@std/fmt/colors"; + * + * console.log(bgYellow("Hello, world!")); + * ``` + * + * @param str The text to make its background yellow + * @returns The text with yellow background */ export function bgYellow(str: string): string { return run(str, code([43], 49)); @@ -352,7 +639,16 @@ export function bgYellow(str: string): string { /** * Set background color to blue. - * @param str text to make its background blue + * + * @example Usage + * ```ts + * import { bgBlue } from "@std/fmt/colors"; + * + * console.log(bgBlue("Hello, world!")); + * ``` + * + * @param str The text to make its background blue + * @returns The text with blue background */ export function bgBlue(str: string): string { return run(str, code([44], 49)); @@ -360,7 +656,16 @@ export function bgBlue(str: string): string { /** * Set background color to magenta. - * @param str text to make its background magenta + * + * @example Usage + * ```ts + * import { bgMagenta } from "@std/fmt/colors"; + * + * console.log(bgMagenta("Hello, world!")); + * ``` + * + * @param str The text to make its background magenta + * @returns The text with magenta background */ export function bgMagenta(str: string): string { return run(str, code([45], 49)); @@ -368,7 +673,16 @@ export function bgMagenta(str: string): string { /** * Set background color to cyan. - * @param str text to make its background cyan + * + * @example Usage + * ```ts + * import { bgCyan } from "@std/fmt/colors"; + * + * console.log(bgCyan("Hello, world!")); + * ``` + * + * @param str The text to make its background cyan + * @returns The text with cyan background */ export function bgCyan(str: string): string { return run(str, code([46], 49)); @@ -376,7 +690,16 @@ export function bgCyan(str: string): string { /** * Set background color to white. - * @param str text to make its background white + * + * @example Usage + * ```ts + * import { bgWhite } from "@std/fmt/colors"; + * + * console.log(bgWhite("Hello, world!")); + * ``` + * + * @param str The text to make its background white + * @returns The text with white background */ export function bgWhite(str: string): string { return run(str, code([47], 49)); @@ -384,7 +707,16 @@ export function bgWhite(str: string): string { /** * Set background color to bright black. - * @param str text to make its background bright-black + * + * @example Usage + * ```ts + * import { bgBrightBlack } from "@std/fmt/colors"; + * + * console.log(bgBrightBlack("Hello, world!")); + * ``` + * + * @param str The text to make its background bright black + * @returns The text with bright black background */ export function bgBrightBlack(str: string): string { return run(str, code([100], 49)); @@ -392,7 +724,16 @@ export function bgBrightBlack(str: string): string { /** * Set background color to bright red. - * @param str text to make its background bright-red + * + * @example Usage + * ```ts + * import { bgBrightRed } from "@std/fmt/colors"; + * + * console.log(bgBrightRed("Hello, world!")); + * ``` + * + * @param str The text to make its background bright red + * @returns The text with bright red background */ export function bgBrightRed(str: string): string { return run(str, code([101], 49)); @@ -400,7 +741,16 @@ export function bgBrightRed(str: string): string { /** * Set background color to bright green. - * @param str text to make its background bright-green + * + * @example Usage + * ```ts + * import { bgBrightGreen } from "@std/fmt/colors"; + * + * console.log(bgBrightGreen("Hello, world!")); + * ``` + * + * @param str The text to make its background bright green + * @returns The text with bright green background */ export function bgBrightGreen(str: string): string { return run(str, code([102], 49)); @@ -408,7 +758,16 @@ export function bgBrightGreen(str: string): string { /** * Set background color to bright yellow. - * @param str text to make its background bright-yellow + * + * @example Usage + * ```ts + * import { bgBrightYellow } from "@std/fmt/colors"; + * + * console.log(bgBrightYellow("Hello, world!")); + * ``` + * + * @param str The text to make its background bright yellow + * @returns The text with bright yellow background */ export function bgBrightYellow(str: string): string { return run(str, code([103], 49)); @@ -416,7 +775,16 @@ export function bgBrightYellow(str: string): string { /** * Set background color to bright blue. - * @param str text to make its background bright-blue + * + * @example Usage + * ```ts + * import { bgBrightBlue } from "@std/fmt/colors"; + * + * console.log(bgBrightBlue("Hello, world!")); + * ``` + * + * @param str The text to make its background bright blue + * @returns The text with bright blue background */ export function bgBrightBlue(str: string): string { return run(str, code([104], 49)); @@ -424,7 +792,16 @@ export function bgBrightBlue(str: string): string { /** * Set background color to bright magenta. - * @param str text to make its background bright-magenta + * + * @example Usage + * ```ts + * import { bgBrightMagenta } from "@std/fmt/colors"; + * + * console.log(bgBrightMagenta("Hello, world!")); + * ``` + * + * @param str The text to make its background bright magenta + * @returns The text with bright magenta background */ export function bgBrightMagenta(str: string): string { return run(str, code([105], 49)); @@ -432,7 +809,16 @@ export function bgBrightMagenta(str: string): string { /** * Set background color to bright cyan. - * @param str text to make its background bright-cyan + * + * @example Usage + * ```ts + * import { bgBrightCyan } from "@std/fmt/colors"; + * + * console.log(bgBrightCyan("Hello, world!")); + * ``` + * + * @param str The text to make its background bright cyan + * @returns The text with bright cyan background */ export function bgBrightCyan(str: string): string { return run(str, code([106], 49)); @@ -440,7 +826,16 @@ export function bgBrightCyan(str: string): string { /** * Set background color to bright white. - * @param str text to make its background bright-white + * + * @example Usage + * ```ts + * import { bgBrightWhite } from "@std/fmt/colors"; + * + * console.log(bgBrightWhite("Hello, world!")); + * ``` + * + * @param str The text to make its background bright white + * @returns The text with bright white background */ export function bgBrightWhite(str: string): string { return run(str, code([107], 49)); @@ -450,9 +845,9 @@ export function bgBrightWhite(str: string): string { /** * Clam and truncate color codes - * @param n - * @param max number to truncate to - * @param min number to truncate from + * @param n The input number + * @param max The number to truncate to + * @param min The number to truncate from */ function clampAndTruncate(n: number, max = 255, min = 0): number { return Math.trunc(Math.max(Math.min(n, max), min)); @@ -461,8 +856,17 @@ function clampAndTruncate(n: number, max = 255, min = 0): number { /** * Set text color using paletted 8bit colors. * https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit - * @param str text color to apply paletted 8bit colors to - * @param color code + * + * @example Usage + * ```ts + * import { rgb8 } from "@std/fmt/colors"; + * + * console.log(rgb8("Hello, world!", 42)); + * ``` + * + * @param str The text color to apply paletted 8bit colors to + * @param color The color code + * @returns The text with paletted 8bit color */ export function rgb8(str: string, color: number): string { return run(str, code([38, 5, clampAndTruncate(color)], 39)); @@ -471,8 +875,17 @@ export function rgb8(str: string, color: number): string { /** * Set background color using paletted 8bit colors. * https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit - * @param str text color to apply paletted 8bit background colors to + * + * @example Usage + * ```ts + * import { bgRgb8 } from "@std/fmt/colors"; + * + * console.log(bgRgb8("Hello, world!", 42)); + * ``` + * + * @param str The text color to apply paletted 8bit background colors to * @param color code + * @returns The text with paletted 8bit background color */ export function bgRgb8(str: string, color: number): string { return run(str, code([48, 5, clampAndTruncate(color)], 49)); @@ -483,16 +896,16 @@ export function bgRgb8(str: string, color: number): string { * `color` can be a number in range `0x000000` to `0xffffff` or * an `Rgb`. * - * To produce the color magenta: - * + * @example To produce the color magenta: * ```ts * import { rgb24 } from "@std/fmt/colors"; * * rgb24("foo", 0xff00ff); * rgb24("foo", {r: 255, g: 0, b: 255}); * ``` - * @param str text color to apply 24bit rgb to - * @param color code + * @param str The text color to apply 24bit rgb to + * @param color The color code + * @returns The text with 24bit rgb color */ export function rgb24(str: string, color: number | Rgb): string { if (typeof color === "number") { @@ -524,16 +937,16 @@ export function rgb24(str: string, color: number | Rgb): string { * `color` can be a number in range `0x000000` to `0xffffff` or * an `Rgb`. * - * To produce the color magenta: - * + * @example To produce the color magenta: * ```ts * import { bgRgb24 } from "@std/fmt/colors"; * * bgRgb24("foo", 0xff00ff); * bgRgb24("foo", {r: 255, g: 0, b: 255}); * ``` - * @param str text color to apply 24bit rgb to - * @param color code + * @param str The text color to apply 24bit rgb to + * @param color The color code + * @returns The text with 24bit rgb color */ export function bgRgb24(str: string, color: number | Rgb): string { if (typeof color === "number") { @@ -571,9 +984,18 @@ const ANSI_PATTERN = new RegExp( /** * Remove ANSI escape codes from the string. - * @param string to remove ANSI escape codes from * - * @deprecated This will be removed in 1.0.0. Use {@linkcode stripAnsiCode} instead. + * @example Usage + * ```ts + * import { stripColor, red } from "@std/fmt/colors"; + * + * console.log(stripColor(red("Hello, world!"))); + * ``` + * + * @param string The text to remove ANSI escape codes from + * @returns The text without ANSI escape codes + * + * @deprecated This will be removed in 1.0.0. Use {@linkcode stripAnsiCode} instead. */ export function stripColor(string: string): string { return stripAnsiCode(string); @@ -582,7 +1004,15 @@ export function stripColor(string: string): string { /** * Remove ANSI escape codes from the string. * - * @param string to remove ANSI escape codes from + * @example Usage + * ```ts + * import { stripAnsiCode, red } from "@std/fmt/colors"; + * + * console.log(stripAnsiCode(red("Hello, world!"))); + * ``` + * + * @param string The text to remove ANSI escape codes from + * @returns The text without ANSI escape codes */ export function stripAnsiCode(string: string): string { return string.replace(ANSI_PATTERN, ""); diff --git a/fmt/duration.ts b/fmt/duration.ts index b985d5b5d..b37e0928b 100644 --- a/fmt/duration.ts +++ b/fmt/duration.ts @@ -95,6 +95,7 @@ export interface PrettyDurationOptions { /** * Format milliseconds to time duration. * + * @example Usage * ```ts * import { format } from "@std/fmt/duration"; * @@ -103,6 +104,10 @@ export interface PrettyDurationOptions { * format(99674, { ignoreZero: true }); // "1m 39s 674ms" * format(99674, { style: "full", ignoreZero: true }); // "1 minutes, 39 seconds, 674 milliseconds" * ``` + * + * @param ms The milliseconds value to format + * @param options The options for formatting + * @returns The formatted string */ export function format( ms: number, diff --git a/fmt/printf.ts b/fmt/printf.ts index 42ed9c098..35c821d9b 100644 --- a/fmt/printf.ts +++ b/fmt/printf.ts @@ -916,11 +916,25 @@ class Printf { } /** - * Converts and format a variable number of `args` as is specified by `format`. + * Converts and formats a variable number of `args` as is specified by `format`. * `sprintf` returns the formatted string. * - * @param format - * @param args + * See the module documentation for the available format strings. + * + * @example Usage + * ```ts + * import { sprintf } from "@std/fmt/printf"; + * import { assertEquals } from "@std/assert" + * + * assertEquals(sprintf("%d", 9), "9"); + * assertEquals(sprintf("%o", 9), "11"); + * assertEquals(sprintf("%f", 4), "4.000000"); + * assertEquals(sprintf("%.3f", 0.9999), "1.000"); + * ``` + * + * @param format The format string to use + * @param args The arguments to format + * @returns The formatted string */ export function sprintf(format: string, ...args: unknown[]): string { const printf = new Printf(format, ...args); @@ -930,8 +944,21 @@ export function sprintf(format: string, ...args: unknown[]): string { /** * Converts and format a variable number of `args` as is specified by `format`. * `printf` writes the formatted string to standard output. - * @param format - * @param args + * + * See the module documentation for the available format strings. + * + * @example Usage + * ```ts + * import { printf } from "@std/fmt/printf"; + * + * printf("%d", 9); // prints "9" + * printf("%o", 9); // prints "11" + * printf("%f", 4); // prints "4.000000" + * printf("%.3f", 0.9999); // prints "1.000" + * ``` + * + * @param format The format string to use + * @param args The arguments to format */ export function printf(format: string, ...args: unknown[]) { const s = sprintf(format, ...args);