foster/deno
0
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2025-03-03 09:31:22 -05:00
Code Issues Packages 1 Wiki Activity

doc: improve various API docs and include examples (#4486)

Browse source
This commit is contained in:
Chris Knight 2020-03-25 03:54:41 +00:00 • committed by GitHub
parent 3d228f5f9e
commit eeedb416c0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 83 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

111
cli/js/lib.deno.ns.d.ts vendored
View file

@ -146,34 +146,35 @@ declare namespace Deno {
*/
export function osRelease(): string;
/** Exit the Deno process with optional exit code. */
/** Exit the Deno process with optional exit code. If no exit code is supplied
* then Deno will exit with return code of 0.
*
* Deno.exit(5);
*/
export function exit(code?: number): never;
/** Returns a snapshot of the environment variables at invocation. Mutating a
* property in the object will set that variable in the environment for the
* process. The environment object will only accept `string`s as values.
/** Without any parameters, this will return a snapshot of the environment
* variables at invocation. Changing a property in the object will set that
* variable in the environment for the process. The environment object will
* only accept `string`s as values.
*
* Passing in a `string` key parameter will return the value for that environment
* variable, or undefined if that key doesn't exist.
*
* const myEnv = Deno.env();
* console.log(myEnv.SHELL);
* myEnv.TEST_VAR = "HELLO";
* const newEnv = Deno.env();
* console.log(myEnv.TEST_VAR == newEnv.TEST_VAR);
* console.log(myEnv.TEST_VAR === newEnv.TEST_VAR); //outputs "true"
* console.log(Deno.env("TEST_VAR")); //outputs "HELLO"
* console.log(Deno.env("MADE_UP_VAR")); //outputs "Undefined"
*
* Requires `allow-env` permission. */
export function env(): {
[index: string]: string;
};
/** Returns the value of an environment variable at invocation. If the
* variable is not present, `undefined` will be returned.
*
* const myEnv = Deno.env();
* console.log(myEnv.SHELL);
* myEnv.TEST_VAR = "HELLO";
* const newEnv = Deno.env();
* console.log(myEnv.TEST_VAR == newEnv.TEST_VAR);
*
* Requires `allow-env` permission. */
/** See overloaded parent function Deno.env() */
export function env(key: string): string | undefined;
/** **UNSTABLE** */
@ -195,12 +196,14 @@ declare namespace Deno {
| "tmp"
| "video";
// TODO(ry) markdown in jsdoc broken https://deno.land/typedoc/index.html#dir
/**
* **UNSTABLE**: Might rename method `dir` and type alias `DirKind`.
* **UNSTABLE**: Currently under evaluation to decide if method name `dir` and
* parameter type alias name `DirKind` should be renamed.
*
* Returns the user and platform specific directories.
*
* const homeDirectory = Deno.dir("home");
*
* Requires `allow-env` permission.
*
* Returns `null` if there is no applicable directory or if any other error
@ -210,6 +213,14 @@ declare namespace Deno {
* `"data_local"`, `"audio"`, `"desktop"`, `"document"`, `"download"`,
* `"font"`, `"picture"`, `"public"`, `"template"`, `"tmp"`, `"video"`
*
* `"home"`
*
* |Platform | Value | Example |
* | ------- | -----------------------------------------| -----------------------|
* | Linux | `$HOME` | /home/alice |
* | macOS | `$HOME` | /Users/alice |
* | Windows | `{FOLDERID_Profile}` | C:\Users\Alice |
*
* `"cache"`
*
* |Platform | Value | Example |
@ -336,18 +347,23 @@ declare namespace Deno {
/**
* Returns the path to the current deno executable.
*
* console.log(Deno.execPath()); //e.g. "/home/alice/.local/bin/deno"
*
* Requires `allow-env` permission.
*/
export function execPath(): string;
/**
* **UNSTABLE**: maybe needs permissions.
* **UNSTABLE**: Currently under evaluation to decide if explicit permission is
* required to get the value of the current working directory.
*
* Return a string representing the current working directory.
*
* If the current directory can be reached via multiple paths (due to symbolic
* links), `cwd()` may return any one of them.
*
* const currentWorkingDirectory = Deno.cwd();
*
* Throws `Deno.errors.NotFound` if directory not available.
*/
export function cwd(): string;
@ -501,8 +517,16 @@ declare namespace Deno {
* error occurs. It resolves to the number of bytes copied or rejects with
* the first error encountered while copying.
*
* const source = await Deno.open("my_file.txt");
* const buffer = new Deno.Buffer()
* const bytesCopied1 = await Deno.copy(Deno.stdout, source);
* const bytesCopied2 = await Deno.copy(buffer, source);
*
* Because `copy()` is defined to read from `src` until `EOF`, it does not
* treat an `EOF` from `read()` as an error to be reported.
*
* @param dst The destination to copy to
* @param src The source to copy from
*/
export function copy(dst: Writer, src: Reader): Promise<number>;
@ -634,7 +658,9 @@ declare namespace Deno {
* as via opening or creating a file. Closing a file when you are finished
* with it is important to avoid leaking resources.
*
* Deno.close(4);
* const file = await Deno.open("my_file.txt");
* // do work with "file" object
* Deno.close(file.rid);
*/
export function close(rid: number): void;
@ -975,7 +1001,7 @@ declare namespace Deno {
/** Synchronously change owner of a regular file or directory. This functionality
* is not available on Windows.
*
* Deno.chownSync('myFile.txt', 1000, 1002);
* Deno.chownSync("myFile.txt", 1000, 1002);
*
* Requires `allow-write` permission.
*
@ -990,7 +1016,7 @@ declare namespace Deno {
/** Change owner of a regular file or directory. This functionality
* is not available on Windows.
*
* await Deno.chown('myFile.txt', 1000, 1002);
* await Deno.chown("myFile.txt", 1000, 1002);
*
* Requires `allow-write` permission.
*
@ -1724,8 +1750,8 @@ declare namespace Deno {
* Connects to the hostname (default is "127.0.0.1") and port on the named
* transport (default is "tcp").
*
* const conn1 = await Deno.connect({ port: 80 })
* const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 })
* const conn1 = await Deno.connect({ port: 80 });
* const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 });
* const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 });
* const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" });
* const conn5 = await Deno.connect({ address: "/foo/bar.sock", transport: "unix" });
@ -1745,9 +1771,18 @@ declare namespace Deno {
certFile?: string;
}
/** Establishes a secure connection over TLS (transport layer security).
/** Establishes a secure connection over TLS (transport layer security) using
* an optional cert file, hostname (default is "127.0.0.1") and port. The
* cert file is optional and if not included Mozilla's root certificates will
* be used (see also https://github.com/ctz/webpki-roots for specifics)
*
* Requires `allow-net` permission. */
* const conn1 = await Deno.connectTLS({ port: 80 });
* const conn2 = await Deno.connectTLS({ certFile: "./certs/my_custom_root_CA.pem", hostname: "192.0.2.1", port: 80 });
* const conn3 = await Deno.connectTLS({ hostname: "[2001:db8::1]", port: 80 });
* const conn4 = await Deno.connectTLS({ certFile: "./certs/my_custom_root_CA.pem", hostname: "golang.org", port: 80});
*
* Requires `allow-net` permission.
*/
export function connectTLS(options: ConnectTLSOptions): Promise<Conn>;
/** **UNSTABLE**: not sure if broken or not */
@ -1805,9 +1840,23 @@ declare namespace Deno {
paths: string[];
}
/** **UNSTABLE**: new API. Needs docs.
/** **UNSTABLE**: new API, yet to be vetted.
*
* Recursive option is `true` by default. */
* Watch for file system events against one or more `paths`, which can be files
* or directories. These paths must exist already. One user action (e.g.
* `touch test.file`) can generate multiple file system events. Likewise,
* one user action can result in multiple file paths in one event (e.g. `mv
* old_name.txt new_name.txt`). Recursive option is `true` by default and,
* for directories, will watch the specified directory and all sub directories.
* Note that the exact ordering of the events can vary between operating systems.
*
* const iter = Deno.fsEvents("/");
* for await (const event of iter) {
* console.log(">>>> event", event); //e.g. { kind: "create", paths: [ "/foo.txt" ] }
* }
*
* Requires `allow-read` permission.
*/
export function fsEvents(
paths: string | string[],
options?: { recursive: boolean }
@ -2061,7 +2110,13 @@ declare namespace Deno {
/** **UNSTABLE**: new API, yet to be vetted.
*
* Format an array of diagnostic items and return them as a single string.
* Format an array of diagnostic items and return them as a single string in a
* user friendly format.
*
* const [diagnostics, result] = Deno.compile("file_with_compile_issues.ts");
* console.table(diagnostics); //Prints raw diagnostic data
* console.log(Deno.formatDiagnostics(diagnostics)); //User friendly output of diagnostics
*
* @param items An array of diagnostic items to format
*/
export function formatDiagnostics(items: DiagnosticItem[]): string;