From 76a9df1ed85ab9bb149f224d9d94cf3359adfedd Mon Sep 17 00:00:00 2001 From: Leo Kettmeir Date: Tue, 13 Dec 2022 14:14:41 +0100 Subject: [PATCH] docs: use example & default tags (#17032) --- cli/tsc/dts/lib.deno.ns.d.ts | 136 ++++++++++++++++++----------- cli/tsc/dts/lib.deno.unstable.d.ts | 71 +++++++++------ ext/net/lib.deno_net.d.ts | 19 ++-- 3 files changed, 145 insertions(+), 81 deletions(-) diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts index da4ec24ab6..fa68dc1bdd 100644 --- a/cli/tsc/dts/lib.deno.ns.d.ts +++ b/cli/tsc/dts/lib.deno.ns.d.ts @@ -465,7 +465,7 @@ declare namespace Deno { * If set to `true`, the global `env` permission will be requested. * If set to `false`, the global `env` permission will be revoked. * - * Defaults to `false`. + * @default {false} */ env?: "inherit" | boolean | string[]; @@ -474,7 +474,7 @@ declare namespace Deno { * If set to `true`, the global `sys` permission will be requested. * If set to `false`, the global `sys` permission will be revoked. * - * Defaults to `false`. + * @default {false} */ sys?: "inherit" | boolean | string[]; @@ -483,7 +483,7 @@ declare namespace Deno { * If set to `true`, the global `hrtime` permission will be requested. * If set to `false`, the global `hrtime` permission will be revoked. * - * Defaults to `false`. + * @default {false} */ hrtime?: "inherit" | boolean; @@ -494,7 +494,7 @@ declare namespace Deno { * if set to `string[]`, the `net` permission will be requested with the * specified host strings with the format `"[:]`. * - * Defaults to `false`. + * @default {false} * * Examples: * @@ -565,7 +565,7 @@ declare namespace Deno { * If set to `true`, the global `ffi` permission will be requested. * If set to `false`, the global `ffi` permission will be revoked. * - * Defaults to `false`. + * @default {false} */ ffi?: "inherit" | boolean | Array; @@ -576,7 +576,7 @@ declare namespace Deno { * If set to `Array`, the `read` permission will be requested with the * specified file paths. * - * Defaults to `false`. + * @default {false} */ read?: "inherit" | boolean | Array; @@ -585,7 +585,7 @@ declare namespace Deno { * If set to `true`, the global `run` permission will be requested. * If set to `false`, the global `run` permission will be revoked. * - * Defaults to `false`. + * @default {false} */ run?: "inherit" | boolean | Array; @@ -596,7 +596,7 @@ declare namespace Deno { * If set to `Array`, the `write` permission will be requested with the * specified file paths. * - * Defaults to `false`. + * @default {false} */ write?: "inherit" | boolean | Array; } @@ -725,18 +725,18 @@ declare namespace Deno { * not await. This helps in preventing logic errors and memory leaks * in the application code. * - * Defaults to `true`. */ + * @default {true} */ sanitizeOps?: boolean; /** Ensure the test step does not "leak" resources - like open files or * network connections - by ensuring the open resources at the start of the * test match the open resources at the end of the test. * - * Defaults to `true`. */ + * @default {true} */ sanitizeResources?: boolean; /** Ensure the test case does not prematurely cause the process to exit, * for example via a call to {@linkcode Deno.exit}. * - * Defaults to `true`. */ + * @default {true} */ sanitizeExit?: boolean; /** Specifies the permissions that should be used to run the test. * @@ -744,7 +744,7 @@ declare namespace Deno { * to "none" to revoke all permissions, or set a more specific set of * permissions using a {@linkcode PermissionOptionsObject}. * - * Defaults to `"inherit"`. */ + * @default {"inherit"} */ permissions?: PermissionOptions; } @@ -957,7 +957,9 @@ declare namespace Deno { * `only` set to `true` and fail the bench suite. */ only?: boolean; /** Ensure the bench case does not prematurely cause the process to exit, - * for example via a call to {@linkcode Deno.exit}. Defaults to `true`. */ + * for example via a call to {@linkcode Deno.exit}. + * + * @default {true} */ sanitizeExit?: boolean; /** Specifies the permissions that should be used to run the bench. * @@ -965,7 +967,7 @@ declare namespace Deno { * * Set this to `"none"` to revoke all permissions. * - * Defaults to "inherit". + * @default {"inherit"} */ permissions?: PermissionOptions; } @@ -2336,34 +2338,45 @@ declare namespace Deno { * * @category File System */ export interface OpenOptions { - /** Defaults to `true`. Sets the option for read access. This option, when `true`, means that - * the file should be read-able if opened. */ + /** Sets the option for read access. This option, when `true`, means that + * the file should be read-able if opened. + * + * @default {true} */ read?: boolean; - /** Defaults to `false`. Sets the option for write access. This option, when `true`, means that + /** Sets the option for write access. This option, when `true`, means that * the file should be write-able if opened. If the file already exists, * any write calls on it will overwrite its contents, by default without - * truncating it. */ + * truncating it. + * + * @default {false} */ write?: boolean; - /** Defaults to `false`. Sets the option for the append mode. This option, when `true`, means + /** Sets the option for the append mode. This option, when `true`, means * that writes will append to a file instead of overwriting previous * contents. * * Note that setting `{ write: true, append: true }` has the same effect as - * setting only `{ append: true }`. */ + * setting only `{ append: true }`. + * + * @default {false} */ append?: boolean; - /** Defaults to `false`. Sets the option for truncating a previous file. If a file is + /** Sets the option for truncating a previous file. If a file is * successfully opened with this option set it will truncate the file to `0` * size if it already exists. The file must be opened with write access - * for truncate to work. */ + * for truncate to work. + * + * @default {false} */ truncate?: boolean; - /** Defaults to `false`. Sets the option to allow creating a new file, if one doesn't already + /** Sets the option to allow creating a new file, if one doesn't already * exist at the specified path. Requires write or append access to be - * used. */ + * used. + * + * @default {false} */ create?: boolean; - /** Defaults to `false`. If set to `true`, no file, directory, or symlink is - * allowed to exist at the target location. Requires write or append - * access to be used. When createNew is set to `true`, create and truncate - * are ignored. */ + /** If set to `true`, no file, directory, or symlink is allowed to exist at + * the target location. Requires write or append access to be used. When + * createNew is set to `true`, create and truncate are ignored. + * + * @default {false} */ createNew?: boolean; /** Permissions to use if creating the file (defaults to `0o666`, before * the process's umask). @@ -2537,14 +2550,16 @@ declare namespace Deno { * * @category File System */ export interface MkdirOptions { - /** Defaults to `false`. If set to `true`, means that any intermediate - * directories will also be created (as with the shell command `mkdir -p`). + /** If set to `true`, means that any intermediate directories will also be + * created (as with the shell command `mkdir -p`). * * Intermediate directories are created with the same permissions. * * When recursive is set to `true`, succeeds silently (without changing any * permissions) if a directory already exists at the path, or if the path - * is a symlink to an existing directory. */ + * is a symlink to an existing directory. + * + * @default {false} */ recursive?: boolean; /** Permissions to use when creating the directory (defaults to `0o777`, * before the process's umask). @@ -2816,8 +2831,9 @@ declare namespace Deno { * * @category File System */ export interface RemoveOptions { - /** Defaults to `false`. If set to `true`, path will be removed even if - * it's a non-empty directory. */ + /** If set to `true`, path will be removed even if it's a non-empty directory. + * + * @default {false} */ recursive?: boolean; } @@ -3290,15 +3306,20 @@ declare namespace Deno { * @category File System */ export interface WriteFileOptions { - /** Defaults to `false`. If set to `true`, will append to a file instead of - * overwriting previous contents. */ + /** If set to `true`, will append to a file instead of overwriting previous + * contents. + * + * @∂efault {false} */ append?: boolean; /** Sets the option to allow creating a new file, if one doesn't already - * exist at the specified path (defaults to `true`). */ + * exist at the specified path. + * + * @default {true} */ create?: boolean; - /** Defaults to `false`. If set to `true`, no file, directory, or symlink is - * allowed to exist at the target location. When createNew is set to `true`, - * `create` is ignored. */ + /** If set to `true`, no file, directory, or symlink is allowed to exist at + * the target location. When createNew is set to `true`, `create` is ignored. + * + * @∂efault {false} */ createNew?: boolean; /** Permissions always applied to file. */ mode?: number; @@ -3903,24 +3924,41 @@ declare namespace Deno { * * @category Console and Debugging */ export interface InspectOptions { - /** Stylize output with ANSI colors. Defaults to `false`. */ + /** Stylize output with ANSI colors. + * + * @default {false} */ colors?: boolean; /** Try to fit more than one entry of a collection on the same line. - * Defaults to `true`. */ + * + * @default {true} */ compact?: boolean; - /** Traversal depth for nested objects. Defaults to `4`. */ + /** Traversal depth for nested objects. + * + * @default {4} */ depth?: number; - /** The maximum number of iterable entries to print. Defaults to `100`. */ + /** The maximum number of iterable entries to print. + * + * @default {100} */ iterableLimit?: number; - /** Show a Proxy's target and handler. Defaults to `false`. */ + /** Show a Proxy's target and handler. + * + * @default {false} */ showProxy?: boolean; - /** Sort Object, Set and Map entries by key. Defaults to `false`. */ + /** Sort Object, Set and Map entries by key. + * + * @default {false} */ sorted?: boolean; - /** Add a trailing comma for multiline collections. Defaults to `false`. */ + /** Add a trailing comma for multiline collections. + * + * @default {false} */ trailingComma?: boolean; - /*** Evaluate the result of calling getters. Defaults to `false`. */ + /** Evaluate the result of calling getters. + * + * @default {false} */ getters?: boolean; - /** Show an object's non-enumerable properties. Defaults to `false`. */ + /** Show an object's non-enumerable properties. + * + * @default {false} */ showHidden?: boolean; /** The maximum length of a string before it is truncated with an * ellipsis. */ @@ -4852,7 +4890,7 @@ declare namespace Deno { ipAddr: string; /** The port number the query will be sent to. * - * If not specified, defaults to `53`. */ + * @default {53} */ port?: number; }; } diff --git a/cli/tsc/dts/lib.deno.unstable.d.ts b/cli/tsc/dts/lib.deno.unstable.d.ts index d0f1e204af..f1b8d99e90 100644 --- a/cli/tsc/dts/lib.deno.unstable.d.ts +++ b/cli/tsc/dts/lib.deno.unstable.d.ts @@ -256,7 +256,7 @@ declare namespace Deno { /** When `true`, function calls can safely callback into JavaScript or * trigger a garbage collection event. * - * Default is `false`. */ + * @default {false} */ callback?: boolean; } @@ -583,8 +583,7 @@ declare namespace Deno { * permission users should acknowledge in practice that is effectively the * same as running with the `allow-all` permission. * - * An example, given a C library which exports a foreign function named - * `add()`: + * @example Given a C library which exports a foreign function named `add()` * * ```ts * // Determine library extension based on @@ -633,7 +632,9 @@ declare namespace Deno { */ interface UnstableRunOptions extends RunOptions { /** If `true`, clears the environment variables before executing the - * sub-process. Defaults to `false`. */ + * sub-process. + * + * @default {false} */ clearEnv?: boolean; /** For POSIX systems, sets the group ID for the sub process. */ gid?: number; @@ -700,7 +701,7 @@ declare namespace Deno { * A custom `HttpClient` for use with {@linkcode fetch} function. This is * designed to allow custom certificates or proxies to be used with `fetch()`. * - * ```ts + * @example ```ts * const caCert = await Deno.readTextFile("./ca.pem"); * const client = Deno.createHttpClient({ caCerts: [ caCert ] }); * const req = await fetch("https://myserver.com", { client }); @@ -769,13 +770,13 @@ declare namespace Deno { * extension of the web platform Fetch API which allows Deno to use custom * TLS certificates and connect via a proxy while using `fetch()`. * - * ```ts + * @example ```ts * const caCert = await Deno.readTextFile("./ca.pem"); * const client = Deno.createHttpClient({ caCerts: [ caCert ] }); * const response = await fetch("https://myserver.com", { client }); * ``` * - * ```ts + * @example ```ts * const client = Deno.createHttpClient({ * proxy: { url: "http://myproxy.com:8080" } * }); @@ -824,7 +825,9 @@ declare namespace Deno { * port. * * This flag is only supported on Linux. It is silently ignored on other - * platforms. Defaults to `false`. */ + * platforms. + * + * @default {false} */ reusePort?: boolean; } @@ -852,7 +855,7 @@ declare namespace Deno { * process has already bound a socket on it. This effectively steals the * socket from the listener. * - * Defaults to `false`. */ + * @default {false} */ reuseAddress?: boolean; } @@ -1084,9 +1087,9 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Acquire an advisory file-system lock for the provided file. `exclusive` - * defaults to `false`. + * Acquire an advisory file-system lock for the provided file. * + * @param [exclusive=false] * @category File System */ export function flock(rid: number, exclusive?: boolean): Promise; @@ -1094,8 +1097,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * * Acquire an advisory file-system lock synchronously for the provided file. - * `exclusive` defaults to `false`. * + * @param [exclusive=false] * @category File System */ export function flockSync(rid: number, exclusive?: boolean): void; @@ -1430,6 +1433,8 @@ declare namespace Deno { * * Doesn't guarantee that only `env` variables are present, as the OS may * set environmental variables for processes. + * + * @default {false} */ clearEnv?: boolean; /** Environmental variables to pass to the subprocess. */ @@ -1454,19 +1459,19 @@ declare namespace Deno { * * Defaults to `"null"`. */ stdin?: "piped" | "inherit" | "null"; - /** How `stdout` of the spawned process should be handled. + /** How `stdout` of the spawned process should be handled. * - * Defaults to `"piped"` for `output` & `outputSync`, - * and `"inherit"` for `spawn`. */ + * Defaults to `"piped". */ stdout?: "piped" | "inherit" | "null"; - /** How `stderr` of the spawned process should be handled. + /** How `stderr` of the spawned process should be handled. * - * Defaults to "piped" for `output` & `outputSync`, - * and `"inherit"` for `spawn`. */ + * Defaults to `"piped"`. */ stderr?: "piped" | "inherit" | "null"; /** Skips quoting and escaping of the arguments on windows. This option - * is ignored on non-windows platforms. Defaults to `false`. */ + * is ignored on non-windows platforms. + * + * @default {false} */ windowsRawArguments?: boolean; } @@ -1480,6 +1485,8 @@ declare namespace Deno { * If `stdin` is set to `"piped"`, the `stdin` {@linkcode WritableStream} * needs to be closed manually. * + * @example Spawn a subprocess and pipe the output to a file + * * ```ts * const command = new Deno.Command(Deno.execPath(), { * args: [ @@ -1498,6 +1505,8 @@ declare namespace Deno { * const status = await child.status; * ``` * + * @example Spawn a subprocess and collect its output + * * ```ts * const command = new Deno.Command(Deno.execPath(), { * args: [ @@ -1511,6 +1520,8 @@ declare namespace Deno { * console.assert("world\n" === new TextDecoder().decode(stderr)); * ``` * + * @example Spawn a subprocess and collect its output synchronously + * * ```ts * const command = new Deno.Command(Deno.execPath(), { * args: [ @@ -1574,8 +1585,10 @@ declare namespace Deno { /** Waits for the child to exit completely, returning all its output and * status. */ output(): Promise; - /** Kills the process with given {@linkcode Deno.Signal}. Defaults to - * `"SIGTERM"`. */ + /** Kills the process with given {@linkcode Deno.Signal}. + * + * @param [signo="SIGTERM"] + */ kill(signo?: Signal): void; /** Ensure that the status of the child process prevents the Deno process @@ -1606,6 +1619,8 @@ declare namespace Deno { * * Doesn't guarantee that only `env` variables are present, as the OS may * set environmental variables for processes. + * + * @default {false} */ clearEnv?: boolean; /** Environmental variables to pass to the subprocess. */ @@ -1622,7 +1637,7 @@ declare namespace Deno { * corresponding {@linkcode AbortController} by sending the process a * SIGTERM signal. * - * Ignored by {@linkcode Command.outputSync}. + * Not supported in {@linkcode Deno.spawnSync}. */ signal?: AbortSignal; @@ -1632,15 +1647,19 @@ declare namespace Deno { stdin?: "piped" | "inherit" | "null"; /** How `stdout` of the spawned process should be handled. * - * Defaults to `"piped"`. */ + * Defaults to `"piped"` for `output` & `outputSync`, + * and `"inherit"` for `spawn`. */ stdout?: "piped" | "inherit" | "null"; /** How `stderr` of the spawned process should be handled. * - * Defaults to "piped". */ + * Defaults to `"piped"` for `output` & `outputSync`, + * and `"inherit"` for `spawn`. */ stderr?: "piped" | "inherit" | "null"; - /** Skips quoting and escaping of the arguments on Windows. This option - * is ignored on non-windows platforms. Defaults to `false`. */ + /** Skips quoting and escaping of the arguments on windows. This option + * is ignored on non-windows platforms. + * + * @default {false} */ windowsRawArguments?: boolean; } diff --git a/ext/net/lib.deno_net.d.ts b/ext/net/lib.deno_net.d.ts index 1941c04264..e8dd5a9575 100644 --- a/ext/net/lib.deno_net.d.ts +++ b/ext/net/lib.deno_net.d.ts @@ -82,12 +82,13 @@ declare namespace Deno { /** The port to listen on. */ port: number; /** A literal IP address or host name that can be resolved to an IP address. - * If not specified, defaults to `0.0.0.0`. * * __Note about `0.0.0.0`__ While listening `0.0.0.0` works on all platforms, * the browsers on Windows don't work with the address `0.0.0.0`. * You should show the message like `server running on localhost:8080` instead of - * `server running on 0.0.0.0:8080` if your program supports Windows. */ + * `server running on 0.0.0.0:8080` if your program supports Windows. + * + * @default {"0.0.0.0"} */ hostname?: string; } @@ -156,7 +157,9 @@ declare namespace Deno { /** The port to connect to. */ port: number; /** A literal IP address or host name that can be resolved to an IP address. - * If not specified, defaults to `127.0.0.1`. */ + * If not specified, + * + * @default {"127.0.0.1"} */ hostname?: string; transport?: "tcp"; } @@ -184,7 +187,9 @@ declare namespace Deno { /** * **UNSTABLE**: new API, see https://github.com/denoland/deno/issues/13617. * - * Enable/disable the use of Nagle's algorithm. Defaults to true. + * Enable/disable the use of Nagle's algorithm. + * + * @param [nodelay=true] */ setNoDelay(nodelay?: boolean): void; /** @@ -204,7 +209,8 @@ declare namespace Deno { /** The port to connect to. */ port: number; /** A literal IP address or host name that can be resolved to an IP address. - * If not specified, defaults to `127.0.0.1`. */ + * + * @default {"127.0.0.1"} */ hostname?: string; /** * Server certificate file. @@ -243,7 +249,8 @@ declare namespace Deno { /** @category Network */ export interface StartTlsOptions { /** A literal IP address or host name that can be resolved to an IP address. - * If not specified, defaults to `127.0.0.1`. */ + * + * @default {"127.0.0.1"} */ hostname?: string; /** A list of root certificates that will be used in addition to the * default root certificates to verify the peer's certificate.