foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-11-21 15:04:11 -05:00
Code Issues Packages 1 Wiki Activity

docs: use example & default tags (#17032)

Browse source
This commit is contained in:
Leo Kettmeir 2022-12-13 14:14:41 +01:00 committed by GitHub
parent 435948e470
commit 76a9df1ed8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 145 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

136
cli/tsc/dts/lib.deno.ns.d.ts vendored
View file

@ -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
* 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;
};
}

67
cli/tsc/dts/lib.deno.unstable.d.ts vendored
View file

@ -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<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. */
@ -1456,17 +1461,17 @@ declare namespace Deno {
stdin?: "piped" | "inherit" | "null";
/** 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.
*
* 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<CommandOutput>;
/** 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;
}

19
ext/net/lib.deno_net.d.ts vendored
View file

@ -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.