docs(std): add some missing JSDoc (#7765)

Refs #7487

std/fmt/colors.ts

@@ -29,6 +29,7 @@ interface Rgb {
 
 let enabled = !noColor;
 
+/** Set changing text color to enabled or disabled */
 export function setColorEnabled(value: boolean): void {
   if (noColor) {
     return;
@@ -37,6 +38,7 @@ export function setColorEnabled(value: boolean): void {
   enabled = value;
 }
 
+/** Get wheather text color change is enabled or disabled. */
 export function getColorEnabled(): boolean {
   return enabled;
 }
@@ -55,166 +57,207 @@ function run(str: string, code: Code): string {
     : str;
 }
 
+/** Reset the text modified */
 export function reset(str: string): string {
   return run(str, code([0], 0));
 }
 
+/** Make the text bold. */
 export function bold(str: string): string {
   return run(str, code([1], 22));
 }
 
+/** The text emits only a small amount of light. */
 export function dim(str: string): string {
   return run(str, code([2], 22));
 }
 
+/** Make the text italic. */
 export function italic(str: string): string {
   return run(str, code([3], 23));
 }
 
+/** Make the text underline. */
 export function underline(str: string): string {
   return run(str, code([4], 24));
 }
 
+/** Invert background color and text color. */
 export function inverse(str: string): string {
   return run(str, code([7], 27));
 }
 
+/** Make the text hidden. */
 export function hidden(str: string): string {
   return run(str, code([8], 28));
 }
 
+/** Put horizontal line throught the center of the text. */
 export function strikethrough(str: string): string {
   return run(str, code([9], 29));
 }
 
+/** Set text color to black. */
 export function black(str: string): string {
   return run(str, code([30], 39));
 }
 
+/** Set text color to red. */
 export function red(str: string): string {
   return run(str, code([31], 39));
 }
 
+/** Set text color to green. */
 export function green(str: string): string {
   return run(str, code([32], 39));
 }
 
+/** Set text color to yellow. */
 export function yellow(str: string): string {
   return run(str, code([33], 39));
 }
 
+/** Set text color to blue. */
 export function blue(str: string): string {
   return run(str, code([34], 39));
 }
 
+/** Set text color to magenta. */
 export function magenta(str: string): string {
   return run(str, code([35], 39));
 }
 
+/** Set text color to cyan. */
 export function cyan(str: string): string {
   return run(str, code([36], 39));
 }
 
+/** Set text color to white. */
 export function white(str: string): string {
   return run(str, code([37], 39));
 }
 
+/** Set text color to gray. */
 export function gray(str: string): string {
   return brightBlack(str);
 }
 
+/** Set text color to bright black. */
 export function brightBlack(str: string): string {
   return run(str, code([90], 39));
 }
 
+/** Set text color to bright red. */
 export function brightRed(str: string): string {
   return run(str, code([91], 39));
 }
 
+/** Set text color to bright green. */
 export function brightGreen(str: string): string {
   return run(str, code([92], 39));
 }
 
+/** Set text color to bright yellow. */
 export function brightYellow(str: string): string {
   return run(str, code([93], 39));
 }
 
+/** Set text color to bright blue. */
 export function brightBlue(str: string): string {
   return run(str, code([94], 39));
 }
 
+/** Set text color to bright magenta. */
 export function brightMagenta(str: string): string {
   return run(str, code([95], 39));
 }
 
+/** Set text color to bright cyan. */
 export function brightCyan(str: string): string {
   return run(str, code([96], 39));
 }
 
+/** Set text color to bright white. */
 export function brightWhite(str: string): string {
   return run(str, code([97], 39));
 }
 
+/** Set background color to black. */
 export function bgBlack(str: string): string {
   return run(str, code([40], 49));
 }
 
+/** Set background color to red. */
 export function bgRed(str: string): string {
   return run(str, code([41], 49));
 }
 
+/** Set background color to green. */
 export function bgGreen(str: string): string {
   return run(str, code([42], 49));
 }
 
+/** Set background color to yellow. */
 export function bgYellow(str: string): string {
   return run(str, code([43], 49));
 }
 
+/** Set background color to blue. */
 export function bgBlue(str: string): string {
   return run(str, code([44], 49));
 }
 
+/** Set background color to magenta. */
 export function bgMagenta(str: string): string {
   return run(str, code([45], 49));
 }
 
+/** Set background color to cyan. */
 export function bgCyan(str: string): string {
   return run(str, code([46], 49));
 }
 
+/** Set background color to white. */
 export function bgWhite(str: string): string {
   return run(str, code([47], 49));
 }
 
+/** Set background color to bright black. */
 export function bgBrightBlack(str: string): string {
   return run(str, code([100], 49));
 }
 
+/** Set background color to bright red. */
 export function bgBrightRed(str: string): string {
   return run(str, code([101], 49));
 }
 
+/** Set background color to bright green. */
 export function bgBrightGreen(str: string): string {
   return run(str, code([102], 49));
 }
 
+/** Set background color to bright yellow. */
 export function bgBrightYellow(str: string): string {
   return run(str, code([103], 49));
 }
 
+/** Set background color to bright blue. */
 export function bgBrightBlue(str: string): string {
   return run(str, code([104], 49));
 }
 
+/** Set background color to bright magenta. */
 export function bgBrightMagenta(str: string): string {
   return run(str, code([105], 49));
 }
 
+/** Set background color to bright cyan. */
 export function bgBrightCyan(str: string): string {
   return run(str, code([106], 49));
 }
 
+/** Set background color to bright white. */
 export function bgBrightWhite(str: string): string {
   return run(str, code([107], 49));
 }
@@ -314,6 +357,7 @@ const ANSI_PATTERN = new RegExp(
   "g",
 );
 
+/** Remove ANSI escape codes from the string. */
 export function stripColor(string: string): string {
   return string.replace(ANSI_PATTERN, "");
 }

std/fmt/printf.ts

@@ -661,11 +661,19 @@ class Printf {
   }
 }
 
+/**
+ * Converts and format a variable number of `args` as is specified by `format`.
+ * `sprintf` returns the formatted string.
+ */
 export function sprintf(format: string, ...args: unknown[]): string {
   const printf = new Printf(format, ...args);
   return printf.doPrintf();
 }
 
+/**
+ * Converts and format a variable number of `args` as is specified by `format`.
+ * `printf` writes the formatted string to standard output.
+ */
 export function printf(format: string, ...args: unknown[]): void {
   const s = sprintf(format, ...args);
   Deno.stdout.writeSync(new TextEncoder().encode(s));

std/io/streams.ts

@@ -1,5 +1,6 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 
+/** Create a `Writer` from a `WritablseStreamDefaultReader`. */
 export function fromStreamWriter(
   streamWriter: WritableStreamDefaultWriter<Uint8Array>,
 ): Deno.Writer {
@@ -12,6 +13,7 @@ export function fromStreamWriter(
   };
 }
 
+/** Create a `Reader` from a `ReadableSteramDefaultReader`. */
 export function fromStreamReader(
   streamReader: ReadableStreamDefaultReader<Uint8Array>,
 ): Deno.Reader {

std/log/mod.ts

@@ -57,6 +57,7 @@ export const handlers = {
   RotatingFileHandler,
 };
 
+/** Get a logger instance. If not specified `name`, get the default logger.  */
 export function getLogger(name?: string): Logger {
   if (!name) {
     const d = state.loggers.get("default");
@@ -75,6 +76,7 @@ export function getLogger(name?: string): Logger {
   return result;
 }
 
+/** Log with debug level, using default logger. */
 export function debug<T>(msg: () => T, ...args: unknown[]): T | undefined;
 export function debug<T>(
   msg: T extends GenericFunction ? never : T,
@@ -91,6 +93,7 @@ export function debug<T>(
   return getLogger("default").debug(msg, ...args);
 }
 
+/** Log with info level, using default logger. */
 export function info<T>(msg: () => T, ...args: unknown[]): T | undefined;
 export function info<T>(
   msg: T extends GenericFunction ? never : T,
@@ -107,6 +110,7 @@ export function info<T>(
   return getLogger("default").info(msg, ...args);
 }
 
+/** Log with warning level, using default logger. */
 export function warning<T>(msg: () => T, ...args: unknown[]): T | undefined;
 export function warning<T>(
   msg: T extends GenericFunction ? never : T,
@@ -123,6 +127,7 @@ export function warning<T>(
   return getLogger("default").warning(msg, ...args);
 }
 
+/** Log with error level, using default logger. */
 export function error<T>(msg: () => T, ...args: unknown[]): T | undefined;
 export function error<T>(
   msg: T extends GenericFunction ? never : T,
@@ -139,6 +144,7 @@ export function error<T>(
   return getLogger("default").error(msg, ...args);
 }
 
+/** Log with critical level, using default logger. */
 export function critical<T>(msg: () => T, ...args: unknown[]): T | undefined;
 export function critical<T>(
   msg: T extends GenericFunction ? never : T,
@@ -155,6 +161,7 @@ export function critical<T>(
   return getLogger("default").critical(msg, ...args);
 }
 
+/** Setup logger config. */
 export async function setup(config: LogConfig): Promise<void> {
   state.config = {
     handlers: { ...DEFAULT_CONFIG.handlers, ...config.handlers },

std/path/posix.ts

@@ -16,6 +16,7 @@ export const sep = "/";
 export const delimiter = ":";
 
 // path.resolve([from ...], to)
+/** resolves `pathSegments` into an absolute path.  */
 export function resolve(...pathSegments: string[]): string {
   let resolvedPath = "";
   let resolvedAbsolute = false;
@@ -60,6 +61,7 @@ export function resolve(...pathSegments: string[]): string {
   else return ".";
 }
 
+/** Notmalize the `path`, resolving `'..'` and `'.'` segments. */
 export function normalize(path: string): string {
   assertPath(path);
 
@@ -84,6 +86,7 @@ export function isAbsolute(path: string): boolean {
   return path.length > 0 && path.charCodeAt(0) === CHAR_FORWARD_SLASH;
 }
 
+/** Join all given a sequence of `paths`,then normalizes the resulting path. */
 export function join(...paths: string[]): string {
   if (paths.length === 0) return ".";
   let joined: string | undefined;
@@ -99,6 +102,7 @@ export function join(...paths: string[]): string {
   return normalize(joined);
 }
 
+/** Return the relative path from `from` to `to` based on current working directory. */
 export function relative(from: string, to: string): string {
   assertPath(from);
   assertPath(to);
@@ -186,6 +190,7 @@ export function toNamespacedPath(path: string): string {
   return path;
 }
 
+/** Return the directory name of a `path`. */
 export function dirname(path: string): string {
   assertPath(path);
   if (path.length === 0) return ".";
@@ -209,6 +214,7 @@ export function dirname(path: string): string {
   return path.slice(0, end);
 }
 
+/** Return the last portion of a `path`. Trailing directory separators are ignored. */
 export function basename(path: string, ext = ""): string {
   if (ext !== undefined && typeof ext !== "string") {
     throw new TypeError('"ext" argument must be a string');
@@ -283,6 +289,7 @@ export function basename(path: string, ext = ""): string {
   }
 }
 
+/** Return the extention of the `path`. */
 export function extname(path: string): string {
   assertPath(path);
   let startDot = -1;
@@ -333,6 +340,7 @@ export function extname(path: string): string {
   return path.slice(startDot, end);
 }
 
+/** Generate a path from `FormatInputPathObject` object. */
 export function format(pathObject: FormatInputPathObject): string {
   if (pathObject === null || typeof pathObject !== "object") {
     throw new TypeError(
@@ -342,6 +350,7 @@ export function format(pathObject: FormatInputPathObject): string {
   return _format("/", pathObject);
 }
 
+/** Return a `ParsedPath` object of the `path`. */
 export function parse(path: string): ParsedPath {
   assertPath(path);