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

1 files changed, 83 insertions, 28 deletions

diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts
index 72794e3bf..6c3e563d3 100644
--- a/cli/js/lib.deno.ns.d.ts
+++ b/cli/js/lib.deno.ns.d.ts
@@ -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.
+   *
+   * 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" ] }
+   *       }
    *
-   * Recursive option is `true` by default. */
+   * 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;