docs: use example & default tags (#17032)

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 `"<host>[:<port>]`.
      *
-     * 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<string | URL>;
 
@@ -576,7 +576,7 @@ declare namespace Deno {
      * If set to `Array<string | URL>`, the `read` permission will be requested with the
      * specified file paths.
      *
-     * Defaults to `false`.
+     * @default {false}
      */
     read?: "inherit" | boolean | Array<string | URL>;
 
@@ -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<string | URL>;
 
@@ -596,7 +596,7 @@ declare namespace Deno {
      * If set to `Array<string | URL>`, the `write` permission will be requested with the
      * specified file paths.
      *
-     * Defaults to `false`.
+     * @default {false}
      */
     write?: "inherit" | boolean | Array<string | URL>;
   }
@@ -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
+    /** Sets the option for read access. This option, when `true`, means that
-     * the file should be read-able if opened. */
+     * 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
+    /** If set to `true`, no file, directory, or symlink is allowed to exist at
-     * allowed to exist at the target location. Requires write or append
+     * the target location. Requires write or append access to be used. When
-     * access to be used. When createNew is set to `true`, create and truncate
+     * createNew is set to `true`, create and truncate are ignored.
-     * 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
+    /** If set to `true`, means that any intermediate directories will also be
-     * directories will also be created (as with the shell command `mkdir -p`).
+     * 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
+    /** If set to `true`, path will be removed even if it's a non-empty directory.
-     * 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
+    /** If set to `true`, will append to a file instead of overwriting previous
-     * overwriting previous contents. */
+     * 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
+    /** If set to `true`, no file, directory, or symlink is allowed to exist at
-     * allowed to exist at the target location. When createNew is set to `true`,
+     * the target location. When createNew is set to `true`, `create` is ignored.
-     * `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;
     };
   }

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
+   * @example Given a C library which exports a foreign function named `add()`
-   * `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`
+   * Acquire an advisory file-system lock for the provided file.
-   * defaults to `false`.
    *
+   * @param [exclusive=false]
    * @category File System
    */
   export function flock(rid: number, exclusive?: boolean): Promise<void>;
@@ -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`,
+     * Defaults to `"piped". */
-     * and `"inherit"` for `spawn`. */
     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`,
+     * Defaults to `"piped"`. */
-     * 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`. */
+     * 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<CommandOutput>;
-    /** Kills the process with given {@linkcode Deno.Signal}. Defaults to
+    /** Kills the process with given {@linkcode Deno.Signal}.
-     * `"SIGTERM"`. */
+     *
+     * @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
+    /** 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;
   }
 

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.