Cleanup comments and internal variables (#4205)

25 files changed, 681 insertions, 572 deletions

diff --git a/cli/fs.rs b/cli/fs.rs
index c59a49e35..3aae44021 100644
--- a/cli/fs.rs
+++ b/cli/fs.rs
@@ -11,11 +11,10 @@ use rand::Rng;
 use walkdir::WalkDir;
 
 #[cfg(unix)]
+use std::os::unix::fs::{DirBuilderExt, PermissionsExt};
+
+#[cfg(unix)]
 use nix::unistd::{chown as unix_chown, Gid, Uid};
-#[cfg(any(unix))]
-use std::os::unix::fs::DirBuilderExt;
-#[cfg(any(unix))]
-use std::os::unix::fs::PermissionsExt;
 
 pub fn write_file<T: AsRef<[u8]>>(
   filename: &Path,
@@ -48,12 +47,13 @@ pub fn write_file_2<T: AsRef<[u8]>>(
   file.write_all(data.as_ref())
 }
 
-#[cfg(any(unix))]
+#[cfg(unix)]
 fn set_permissions(file: &mut File, perm: u32) -> std::io::Result<()> {
   debug!("set file perm to {}", perm);
   file.set_permissions(PermissionsExt::from_mode(perm & 0o777))
 }
-#[cfg(not(any(unix)))]
+
+#[cfg(not(unix))]
 fn set_permissions(_file: &mut File, _perm: u32) -> std::io::Result<()> {
   // NOOP on windows
   Ok(())
@@ -102,13 +102,13 @@ pub fn mkdir(path: &Path, perm: u32, recursive: bool) -> std::io::Result<()> {
   builder.create(path)
 }
 
-#[cfg(any(unix))]
+#[cfg(unix)]
 fn set_dir_permission(builder: &mut DirBuilder, perm: u32) {
   debug!("set dir perm to {}", perm);
   builder.mode(perm & 0o777);
 }
 
-#[cfg(not(any(unix)))]
+#[cfg(not(unix))]
 fn set_dir_permission(_builder: &mut DirBuilder, _perm: u32) {
   // NOOP on windows
 }
@@ -123,11 +123,11 @@ pub fn chown(path: &str, uid: u32, gid: u32) -> Result<(), ErrBox> {
 
 #[cfg(not(unix))]
 pub fn chown(_path: &str, _uid: u32, _gid: u32) -> Result<(), ErrBox> {
-  // Noop
+  // FAIL on Windows
   // TODO: implement chown for Windows
   let e = std::io::Error::new(
     std::io::ErrorKind::Other,
-    "Op not implemented".to_string(),
+    "Not implemented".to_string(),
   );
   Err(ErrBox::from(e))
 }
diff --git a/cli/js/chmod.ts b/cli/js/chmod.ts
index 22bd8c40e..5aa4ce7ea 100644
--- a/cli/js/chmod.ts
+++ b/cli/js/chmod.ts
@@ -1,19 +1,22 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "./dispatch_json.ts";
 
-/** Changes the permission of a specific file/directory of specified path
- * synchronously.
+/** Synchronously changes the permission of a specific file/directory of
+ * specified path.  Ignores the process's umask.
  *
  *       Deno.chmodSync("/path/to/file", 0o666);
- */
+ *
+ * Requires `allow-write` permission. */
 export function chmodSync(path: string, mode: number): void {
   sendSync("op_chmod", { path, mode });
 }
 
 /** Changes the permission of a specific file/directory of specified path.
+ * Ignores the process's umask.
  *
  *       await Deno.chmod("/path/to/file", 0o666);
- */
+ *
+ * Requires `allow-write` permission. */
 export async function chmod(path: string, mode: number): Promise<void> {
   await sendAsync("op_chmod", { path, mode });
 }
diff --git a/cli/js/chown.ts b/cli/js/chown.ts
index d56be3dc2..e39741546 100644
--- a/cli/js/chown.ts
+++ b/cli/js/chown.ts
@@ -1,8 +1,11 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "./dispatch_json.ts";
 
-/**
- * Change owner of a regular file or directory synchronously. Unix only at the moment.
+/** Synchronously change owner of a regular file or directory. Linux/Mac OS
+ * only at the moment.
+ *
+ * Requires `allow-write` permission.
+ *
  * @param path path to the file
  * @param uid user id of the new owner
  * @param gid group id of the new owner
@@ -11,8 +14,11 @@ export function chownSync(path: string, uid: number, gid: number): void {
   sendSync("op_chown", { path, uid, gid });
 }
 
-/**
- * Change owner of a regular file or directory asynchronously. Unix only at the moment.
+/** Change owner of a regular file or directory. Linux/Mac OS only at the
+ * moment.
+ *
+ * Requires `allow-write` permission.
+ *
  * @param path path to the file
  * @param uid user id of the new owner
  * @param gid group id of the new owner
diff --git a/cli/js/copy_file.ts b/cli/js/copy_file.ts
index 8ab013aab..6da50d1f6 100644
--- a/cli/js/copy_file.ts
+++ b/cli/js/copy_file.ts
@@ -1,29 +1,29 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "./dispatch_json.ts";
 
-/** Copies the contents of a file to another by name synchronously.
- * Creates a new file if target does not exists, and if target exists,
- * overwrites original content of the target file.
- *
- * It would also copy the permission of the original file
- * to the destination.
+/** Synchronously copies the contents and permissions of one file to another
+ * specified path, by default creating a new file if needed, else overwriting.
+ * Fails if target path is a directory or is unwritable.
  *
  *       Deno.copyFileSync("from.txt", "to.txt");
- */
-export function copyFileSync(from: string, to: string): void {
-  sendSync("op_copy_file", { from, to });
+ *
+ * Requires `allow-read` permission on fromPath.
+ * Requires `allow-write` permission on toPath. */
+export function copyFileSync(fromPath: string, toPath: string): void {
+  sendSync("op_copy_file", { from: fromPath, to: toPath });
 }
 
-/** Copies the contents of a file to another by name.
- *
- * Creates a new file if target does not exists, and if target exists,
- * overwrites original content of the target file.
- *
- * It would also copy the permission of the original file
- * to the destination.
+/** Copies the contents and permissions of one file to another specified path,
+ * by default creating a new file if needed, else overwriting. Fails if target
+ * path is a directory or is unwritable.
  *
  *       await Deno.copyFile("from.txt", "to.txt");
- */
-export async function copyFile(from: string, to: string): Promise<void> {
-  await sendAsync("op_copy_file", { from, to });
+ *
+ * Requires `allow-read` permission on fromPath.
+ * Requires `allow-write` permission on toPath. */
+export async function copyFile(
+  fromPath: string,
+  toPath: string
+): Promise<void> {
+  await sendAsync("op_copy_file", { from: fromPath, to: toPath });
 }
diff --git a/cli/js/dir.ts b/cli/js/dir.ts
index eea2ef691..bc62be83f 100644
--- a/cli/js/dir.ts
+++ b/cli/js/dir.ts
@@ -2,19 +2,25 @@
 import { sendSync } from "./dispatch_json.ts";
 
 /**
- * `cwd()` 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.
- * throws `NotFound` exception if directory not available
+ * **UNSTABLE**: maybe needs permissions.
+ *
+ * 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.
+ *
+ * Throws `Deno.errors.NotFound` if directory not available.
  */
 export function cwd(): string {
   return sendSync("op_cwd");
 }
 
 /**
- * `chdir()` Change the current working directory to path.
- * throws `NotFound` exception if directory not available
+ * **UNSTABLE**: maybe needs permissions.
+ *
+ * Change the current working directory to the specified path.
+ *
+ * Throws `Deno.errors.NotFound` if directory not available.
  */
 export function chdir(directory: string): void {
   sendSync("op_chdir", { directory });
diff --git a/cli/js/file_info.ts b/cli/js/file_info.ts
index f0ab5bf6c..18f68e0d5 100644
--- a/cli/js/file_info.ts
+++ b/cli/js/file_info.ts
@@ -3,72 +3,69 @@ import { StatResponse } from "./stat.ts";
 import { build } from "./build.ts";
 
 /** A FileInfo describes a file and is returned by `stat`, `lstat`,
- * `statSync`, `lstatSync`.
- */
+ * `statSync`, `lstatSync`. A list of FileInfo is returned by `readDir`,
+ * `readDirSync`. */
 export interface FileInfo {
   /** The size of the file, in bytes. */
   len: number;
   /** The last modification time of the file. This corresponds to the `mtime`
-   * field from `stat` on Unix and `ftLastWriteTime` on Windows. This may not
-   * be available on all platforms.
-   */
+   * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This
+   * may not be available on all platforms. */
   modified: number | null;
   /** The last access time of the file. This corresponds to the `atime`
    * field from `stat` on Unix and `ftLastAccessTime` on Windows. This may not
-   * be available on all platforms.
-   */
+   * be available on all platforms. */
   accessed: number | null;
   /** The last access time of the file. This corresponds to the `birthtime`
-   * field from `stat` on Unix and `ftCreationTime` on Windows. This may not
-   * be available on all platforms.
-   */
+   * field from `stat` on Mac/BSD and `ftCreationTime` on Windows. This may not
+   * be available on all platforms. */
   created: number | null;
-
   /** The file or directory name. */
   name: string | null;
-
-  /** ID of the device containing the file. Unix only. */
+  /** ID of the device containing the file.
+   *
+   * _Linux/Mac OS only._ */
   dev: number | null;
-
-  /** Inode number. Unix only. */
+  /** Inode number.
+   *
+   * _Linux/Mac OS only._ */
   ino: number | null;
-
   /** The underlying raw st_mode bits that contain the standard Unix permissions
    * for this file/directory. TODO Match behavior with Go on windows for mode.
    */
   mode: number | null;
-
-  /** Number of hard links pointing to this file. Unix only. */
+  /** Number of hard links pointing to this file.
+   *
+   * _Linux/Mac OS only._ */
   nlink: number | null;
-
-  /** User ID of the owner of this file. Unix only. */
+  /** User ID of the owner of this file.
+   *
+   * _Linux/Mac OS only._ */
   uid: number | null;
-
-  /** User ID of the owner of this file. Unix only. */
+  /** User ID of the owner of this file.
+   *
+   * _Linux/Mac OS only._ */
   gid: number | null;
-
-  /** Device ID of this file. Unix only. */
+  /** Device ID of this file.
+   *
+   * _Linux/Mac OS only._ */
   rdev: number | null;
-
-  /** Blocksize for filesystem I/O. Unix only. */
+  /** Blocksize for filesystem I/O.
+   *
+   * _Linux/Mac OS only._ */
   blksize: number | null;
-
-  /** Number of blocks allocated to the file, in 512-byte units. Unix only. */
+  /** Number of blocks allocated to the file, in 512-byte units.
+   *
+   * _Linux/Mac OS only._ */
   blocks: number | null;
-
   /** Returns whether this is info for a regular file. This result is mutually
-   * exclusive to `FileInfo.isDirectory` and `FileInfo.isSymlink`.
-   */
+   * exclusive to `FileInfo.isDirectory` and `FileInfo.isSymlink`. */
   isFile(): boolean;
-
   /** Returns whether this is info for a regular directory. This result is
-   * mutually exclusive to `FileInfo.isFile` and `FileInfo.isSymlink`.
-   */
+   * mutually exclusive to `FileInfo.isFile` and `FileInfo.isSymlink`. */
   isDirectory(): boolean;
-
   /** Returns whether this is info for a symlink. This result is
-   * mutually exclusive to `FileInfo.isFile` and `FileInfo.isDirectory`.
-   */
+   * mutually exclusive to `FileInfo.isFile` and `FileInfo.isDirectory`. */
   isSymlink(): boolean;
 }
 
diff --git a/cli/js/files.ts b/cli/js/files.ts
index 54c1f26bf..d66870309 100644
--- a/cli/js/files.ts
+++ b/cli/js/files.ts
@@ -21,19 +21,23 @@ import { OPS_CACHE } from "./runtime.ts";
 let OP_READ = -1;
 let OP_WRITE = -1;
 
-/** Open a file and return an instance of the `File` object
- *  synchronously.
+/** Synchronously open a file and return an instance of the `File` object.
  *
  *       const file = Deno.openSync("/foo/bar.txt", { read: true, write: true });
+ *
+ * Requires `allow-read` and `allow-write` permissions depending on mode.
  */
-export function openSync(filename: string, capability?: OpenOptions): File;
-/** Open a file and return an instance of the `File` object
- *  synchronously.
+export function openSync(filename: string, mode?: OpenOptions): File;
+
+/** Synchronously open a file and return an instance of the `File` object.
  *
  *       const file = Deno.openSync("/foo/bar.txt", "r");
+ *
+ * Requires `allow-read` and `allow-write` permissions depending on mode.
  */
 export function openSync(filename: string, mode?: OpenMode): File;
 
+/**@internal*/
 export function openSync(
   filename: string,
   modeOrOptions: OpenOptions | OpenMode = "r"
@@ -52,18 +56,22 @@ export function openSync(
   return new File(rid);
 }
 
-/** Open a file and return an instance of the `File` object.
+/** Open a file and resolve to an instance of the `File` object.
  *
  *     const file = await Deno.open("/foo/bar.txt", { read: true, write: true });
+ *
+ * Requires `allow-read` and `allow-write` permissions depending on mode.
  */
 export async function open(
   filename: string,
   options?: OpenOptions
 ): Promise<File>;
 
-/** Open a file and return an instance of the `File` object.
+/** Open a file and resolves to an instance of `Deno.File`.
  *
  *     const file = await Deno.open("/foo/bar.txt, "w+");
+ *
+ * Requires `allow-read` and `allow-write` permissions depending on mode.
  */
 export async function open(filename: string, mode?: OpenMode): Promise<File>;
 
@@ -91,32 +99,35 @@ export async function open(
 }
 
 /** Creates a file if none exists or truncates an existing file and returns
- *  an instance of the `File` object synchronously.
+ *  an instance of `Deno.File`.
  *
  *       const file = Deno.createSync("/foo/bar.txt");
+ *
+ * Requires `allow-read` and `allow-write` permissions.
  */
 export function createSync(filename: string): File {
   return openSync(filename, "w+");
 }
 
-/** Creates a file if none exists or truncates an existing file and returns
- *  an instance of the `File` object.
+/** Creates a file if none exists or truncates an existing file and resolves to
+ *  an instance of `Deno.File`.
  *
  *       const file = await Deno.create("/foo/bar.txt");
+ *
+ * Requires `allow-read` and `allow-write` permissions.
  */
 export function create(filename: string): Promise<File> {
   return open(filename, "w+");
 }
 
-/** Read synchronously from a file ID into an array buffer.
+/** Synchronously read from a file ID into an array buffer.
  *
- * Return `number | EOF` for the operation.
+ * Returns `number | EOF` for the operation.
  *
  *      const file = Deno.openSync("/foo/bar.txt");
  *      const buf = new Uint8Array(100);
  *      const nread = Deno.readSync(file.rid, buf);
  *      const text = new TextDecoder().decode(buf);
- *
  */
 export function readSync(rid: number, p: Uint8Array): number | EOF {
   if (p.length == 0) {
@@ -135,9 +146,9 @@ export function readSync(rid: number, p: Uint8Array): number | EOF {
   }
 }
 
-/** Read from a file ID into an array buffer.
+/** Read from a resource ID into an array buffer.
  *
- * Resolves with the `number | EOF` for the operation.
+ * Resolves to the `number | EOF` for the operation.
  *
  *       const file = await Deno.open("/foo/bar.txt");
  *       const buf = new Uint8Array(100);
@@ -161,9 +172,9 @@ export async function read(rid: number, p: Uint8Array): Promise<number | EOF> {
   }
 }
 
-/** Write synchronously to the file ID the contents of the array buffer.
+/** Synchronously write to the resource ID the contents of the array buffer.
  *
- * Resolves with the number of bytes written.
+ * Resolves to the number of bytes written.
  *
  *       const encoder = new TextEncoder();
  *       const data = encoder.encode("Hello world\n");
@@ -182,15 +193,14 @@ export function writeSync(rid: number, p: Uint8Array): number {
   }
 }
 
-/** Write to the file ID the contents of the array buffer.
+/** Write to the resource ID the contents of the array buffer.
  *
- * Resolves with the number of bytes written.
+ * Resolves to the number of bytes written.
  *
  *      const encoder = new TextEncoder();
  *      const data = encoder.encode("Hello world\n");
  *      const file = await Deno.open("/foo/bar.txt", {create: true, write: true});
  *      await Deno.write(file.rid, data);
- *
  */
 export async function write(rid: number, p: Uint8Array): Promise<number> {
   if (OP_WRITE < 0) {
@@ -204,7 +214,7 @@ export async function write(rid: number, p: Uint8Array): Promise<number> {
   }
 }
 
-/** Seek a file ID synchronously to the given offset under mode given by `whence`.
+/** Synchronously seek a file ID to the given offset under mode given by `whence`.
  *
  *       const file = Deno.openSync("/foo/bar.txt");
  *       Deno.seekSync(file.rid, 0, 0);
@@ -226,7 +236,7 @@ export async function seek(
   await sendAsyncJson("op_seek", { rid, offset, whence });
 }
 
-/** Close the file ID. */
+/** Close the given resource ID. */
 export function close(rid: number): void {
   sendSyncJson("op_close", { rid });
 }
@@ -272,68 +282,57 @@ export class File
   }
 }
 
-/** An instance of `File` for stdin. */
+/** An instance of `Deno.File` for `stdin`. */
 export const stdin = new File(0);
-/** An instance of `File` for stdout. */
+/** An instance of `Deno.File` for `stdout`. */
 export const stdout = new File(1);
-/** An instance of `File` for stderr. */
+/** An instance of `Deno.File` for `stderr`. */
 export const stderr = new File(2);
 
 export interface OpenOptions {
-  /** Sets the option for read access. This option, when true, will indicate 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. */
   read?: boolean;
-  /** Sets the option for write access.
-   * This option, when true, will indicate that the file should be write-able if opened.
-   * If the file already exists, any write calls on it will overwrite its contents, without truncating it.
-   */
+  /** 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. */
   write?: boolean;
-  /** Sets the option for creating a new file.
-   * This option indicates whether a new file will be created if the file does not yet already exist.
-   * In order for the file to be created, write or append access must be used.
-   */
-  create?: boolean;
-  /** 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 length if it already exists.
-   * The file must be opened with write access for truncate to work.
-   */
-  truncate?: boolean;
-  /**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 }.
-   */
+  /**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 }`. */
   append?: boolean;
-  /** Sets the option to always create a new file.
-   * This option indicates whether a new file will be created. No file is allowed to exist at the target location, also no (dangling) symlink.
-   * If { createNew: true } is set, create and truncate are ignored.
-   */
+  /** 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`
+   * length if it already exists. The file must be opened with write access
+   * for truncate to work. */
+  truncate?: boolean;
+  /** 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. */
+  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. */
   createNew?: boolean;
 }
 
-export type OpenMode =
-  /** Read-only. Default. Starts at beginning of file. */
-  | "r"
-  /** Read-write. Start at beginning of file. */
-  | "r+"
-  /** Write-only. Opens and truncates existing file or creates new one for
-   * writing only.
-   */
-  | "w"
-  /** Read-write. Opens and truncates existing file or creates new one for
-   * writing and reading.
-   */
-  | "w+"
-  /** Write-only. Opens existing file or creates new one. Each write appends
-   * content to the end of file.
-   */
-  | "a"
-  /** Read-write. Behaves like "a" and allows to read from file. */
-  | "a+"
-  /** Write-only. Exclusive create - creates new file only if one doesn't exist
-   * already.
-   */
-  | "x"
-  /** Read-write. Behaves like `x` and allows to read from file. */
-  | "x+";
+/** A set of string literals which specify the open mode of a file.
+ *
+ * |Value |Description                                                                                       |
+ * |------|--------------------------------------------------------------------------------------------------|
+ * |`"r"` |Read-only. Default. Starts at beginning of file.                                                  |
+ * |`"r+"`|Read-write. Start at beginning of file.                                                           |
+ * |`"w"` |Write-only. Opens and truncates existing file or creates new one for writing only.                |
+ * |`"w+"`|Read-write. Opens and truncates existing file or creates new one for writing and reading.         |
+ * |`"a"` |Write-only. Opens existing file or creates new one. Each write appends content to the end of file.|
+ * |`"a+"`|Read-write. Behaves like `"a"` and allows to read from file.                                      |
+ * |`"x"` |Write-only. Exclusive create - creates new file only if one doesn't exist already.                |
+ * |`"x+"`|Read-write. Behaves like `x` and allows reading from file.                                        |
+ */
+export type OpenMode = "r" | "r+" | "w" | "w+" | "a" | "a+" | "x" | "x+";
 
 /** Check if OpenOptions is set to valid combination of options.
  *  @returns Tuple representing if openMode is valid and error message if it's not
diff --git a/cli/js/io.ts b/cli/js/io.ts
index 348394061..151c69f22 100644
--- a/cli/js/io.ts
+++ b/cli/js/io.ts
@@ -8,6 +8,7 @@ export type EOF = typeof EOF;
 
 // Seek whence values.
 // https://golang.org/pkg/io/#pkg-constants
+/** **UNSTABLE**: might remove `"SEEK_"` prefix. Might not use all-caps. */
 export enum SeekMode {
   SEEK_START = 0,
   SEEK_CURRENT = 1,
@@ -16,50 +17,79 @@ export enum SeekMode {
 
 // Reader is the interface that wraps the basic read() method.
 // https://golang.org/pkg/io/#Reader
+/** **UNSTABLE**: might make `Reader` into iterator of some sort. */
 export interface Reader {
-  /** Reads up to p.byteLength bytes into `p`. It resolves to the number
-   * of bytes read (`0` <= `n` <= `p.byteLength`) and rejects if any error encountered.
-   * Even if `read()` returns `n` < `p.byteLength`, it may use all of `p` as
-   * scratch space during the call. If some data is available but not
-   * `p.byteLength` bytes, `read()` conventionally returns what is available
-   * instead of waiting for more.
+  /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number of
+   * bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error
+   * encountered. Even if `read()` resolves to `n` < `p.byteLength`, it may
+   * use all of `p` as scratch space during the call. If some data is
+   * available but not `p.byteLength` bytes, `read()` conventionally resolves
+   * to what is available instead of waiting for more.
    *
-   * When `p.byteLength` == `0`, `read()` returns `0` and has no other effects.
-   *
-   * When `read()` encounters end-of-file condition, it returns EOF symbol.
+   * When `read()` encounters end-of-file condition, it resolves to
+   * `Deno.EOF` symbol.
    *
    * When `read()` encounters an error, it rejects with an error.
    *
    * Callers should always process the `n` > `0` bytes returned before
-   * considering the EOF. Doing so correctly handles I/O errors that happen
+   * considering the `EOF`. Doing so correctly handles I/O errors that happen
    * after reading some bytes and also both of the allowed EOF behaviors.
    *
-   * Implementations must not retain `p`.
+   * Implementations should not retain a reference to `p`.
    */
   read(p: Uint8Array): Promise<number | EOF>;
 }
 
 export interface SyncReader {
+  /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number
+   * of bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error
+   * encountered. Even if `read()` returns `n` < `p.byteLength`, it may use
+   * all of `p` as scratch space during the call. If some data is available
+   * but not `p.byteLength` bytes, `read()` conventionally returns what is
+   * available instead of waiting for more.
+   *
+   * When `readSync()` encounters end-of-file condition, it returns `Deno.EOF`
+   * symbol.
+   *
+   * When `readSync()` encounters an error, it throws with an error.
+   *
+   * Callers should always process the `n` > `0` bytes returned before
+   * considering the `EOF`. Doing so correctly handles I/O errors that happen
+   * after reading some bytes and also both of the allowed EOF behaviors.
+   *
+   * Implementations should not retain a reference to `p`.
+   */
   readSync(p: Uint8Array): number | EOF;
 }
 
 // Writer is the interface that wraps the basic write() method.
 // https://golang.org/pkg/io/#Writer
 export interface Writer {
-  /** Writes `p.byteLength` bytes from `p` to the underlying data
-   * stream. It resolves to the number of bytes written from `p` (`0` <= `n` <=
-   * `p.byteLength`) and any error encountered that caused the write to stop
-   * early. `write()` must return a non-null error if it returns `n` <
-   * `p.byteLength`. write() must not modify the slice data, even temporarily.
+  /** Writes `p.byteLength` bytes from `p` to the underlying data stream. It
+   * resolves to the number of bytes written from `p` (`0` <= `n` <=
+   * `p.byteLength`) or reject with the error encountered that caused the
+   * write to stop early. `write()` must reject with a non-null error if
+   * would resolve to `n` < `p.byteLength`. `write()` must not modify the
+   * slice data, even temporarily.
    *
-   * Implementations must not retain `p`.
+   * Implementations should not retain a reference to `p`.
    */
   write(p: Uint8Array): Promise<number>;
 }
 
 export interface SyncWriter {
+  /** Writes `p.byteLength` bytes from `p` to the underlying data
+   * stream. It returns the number of bytes written from `p` (`0` <= `n`
+   * <= `p.byteLength`) and any error encountered that caused the write to
+   * stop early. `writeSync()` must throw a non-null error if it returns `n` <
+   * `p.byteLength`. `writeSync()` must not modify the slice data, even
+   * temporarily.
+   *
+   * Implementations should not retain a reference to `p`.
+   */
   writeSync(p: Uint8Array): number;
 }
+
 // https://golang.org/pkg/io/#Closer
 export interface Closer {
   // The behavior of Close after the first call is undefined. Specific
@@ -70,19 +100,27 @@ export interface Closer {
 // https://golang.org/pkg/io/#Seeker
 export interface Seeker {
   /** Seek sets the offset for the next `read()` or `write()` to offset,
-   * interpreted according to `whence`: `SeekStart` means relative to the start
-   * of the file, `SeekCurrent` means relative to the current offset, and
-   * `SeekEnd` means relative to the end. Seek returns the new offset relative
-   * to the start of the file and an error, if any.
+   * interpreted according to `whence`: `SEEK_START` means relative to the
+   * start of the file, `SEEK_CURRENT` means relative to the current offset,
+   * and `SEEK_END` means relative to the end.
    *
    * Seeking to an offset before the start of the file is an error. Seeking to
-   * any positive offset is legal, but the behavior of subsequent I/O operations
-   * on the underlying object is implementation-dependent.
+   * any positive offset is legal, but the behavior of subsequent I/O
+   * operations on the underlying object is implementation-dependent.
    */
   seek(offset: number, whence: SeekMode): Promise<void>;
 }
 
 export interface SyncSeeker {
+  /** Seek sets the offset for the next `readSync()` or `writeSync()` to
+   * offset, interpreted according to `whence`: `SEEK_START` means relative
+   * to the start of the file, `SEEK_CURRENT` means relative to the current
+   * offset, and `SEEK_END` means relative to the end.
+   *
+   * Seeking to an offset before the start of the file is an error. Seeking to
+   * any positive offset is legal, but the behavior of subsequent I/O
+   * operations on the underlying object is implementation-dependent.
+   */
   seekSync(offset: number, whence: SeekMode): void;
 }
 
@@ -104,9 +142,9 @@ export interface ReadWriteCloser extends Reader, Writer, Closer {}
 // https://golang.org/pkg/io/#ReadWriteSeeker
 export interface ReadWriteSeeker extends Reader, Writer, Seeker {}
 
-/** Copies from `src` to `dst` until either `EOF` is reached on `src`
- * or an error occurs. It returns the number of bytes copied and the first
- * error encountered while copying, if any.
+/** Copies from `src` to `dst` until either `EOF` is reached on `src` or an
+ * error occurs. It resolves to the number of bytes copied or rejects with
+ * the first error encountered while copying.
  *
  * Because `copy()` is defined to read from `src` until `EOF`, it does not
  * treat an `EOF` from `read()` as an error to be reported.
@@ -130,7 +168,7 @@ export async function copy(dst: Writer, src: Reader): Promise<number> {
 /** Turns `r` into async iterator.
  *
  *      for await (const chunk of toAsyncIterator(reader)) {
- *          console.log(chunk)
+ *        console.log(chunk);
  *      }
  */
 export function toAsyncIterator(r: Reader): AsyncIterableIterator<Uint8Array> {
diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts
index b2e67b288..c54876008 100644
--- a/cli/js/lib.deno.ns.d.ts
+++ b/cli/js/lib.deno.ns.d.ts
@@ -34,7 +34,7 @@ declare namespace Deno {
 
   export interface RunTestsOptions {
     /** If `true`, Deno will exit upon a failure after logging that failure to
-     * the console.  Defaults to `false`. */
+     * the console. Defaults to `false`. */
     exitOnFail?: boolean;
     /** Provide a regular expression of which only tests that match the regular
      * expression are run. */
@@ -42,27 +42,27 @@ declare namespace Deno {
     /** Provide a regular expression of which tests that match the regular
      * expression are skipped. */
     skip?: RegExp;
-    /** Disable logging of the results.  Defaults to `false`. */
+    /** Disable logging of the results. Defaults to `false`. */
     disableLog?: boolean;
   }
 
-  /** Run any tests which have been registered.  Always resolves
+  /** Run any tests which have been registered. Always resolves
    * asynchronously. */
   export function runTests(opts?: RunTestsOptions): Promise<void>;
 
-  /** Get the `loadavg`. Requires the `allow-env` permission.
+  /** Get the `loadavg`. Requires `allow-env` permission.
    *
    *       console.log(Deno.loadavg());
    */
   export function loadavg(): number[];
 
-  /** Get the `hostname`. Requires the `allow-env` permission.
+  /** Get the `hostname`. Requires `allow-env` permission.
    *
    *       console.log(Deno.hostname());
    */
   export function hostname(): string;
 
-  /** Get the OS release. Requires the `allow-env` permission.
+  /** Get the OS release. Requires `allow-env` permission.
    *
    *       console.log(Deno.osRelease());
    */
@@ -81,8 +81,7 @@ declare namespace Deno {
    *       const newEnv = Deno.env();
    *       console.log(myEnv.TEST_VAR == newEnv.TEST_VAR);
    *
-   * Requires the `allow-env` permission.
-   */
+   * Requires `allow-env` permission. */
   export function env(): {
     [index: string]: string;
   };
@@ -96,8 +95,7 @@ declare namespace Deno {
    *       const newEnv = Deno.env();
    *       console.log(myEnv.TEST_VAR == newEnv.TEST_VAR);
    *
-   * Requires the `allow-env` permission.
-   */
+   * Requires `allow-env` permission. */
   export function env(key: string): string | undefined;
 
   /** **UNSTABLE** */
@@ -125,7 +123,7 @@ declare namespace Deno {
    *
    * Returns the user and platform specific directories.
    *
-   * Requires the `allow-env` permission.
+   * Requires `allow-env` permission.
    *
    * Returns `null` if there is no applicable directory or if any other error
    * occurs.
@@ -260,10 +258,12 @@ declare namespace Deno {
   /**
    * Returns the path to the current deno executable.
    *
-   * Requires the `allow-env` permission.
+   * Requires `allow-env` permission.
    */
   export function execPath(): string;
 
+  // @url js/dir.d.ts
+
   /**
    * **UNSTABLE**: maybe needs permissions.
    *
@@ -279,7 +279,7 @@ declare namespace Deno {
   /**
    * **UNSTABLE**: maybe needs permissions.
    *
-   * Change the current working directory to path.
+   * Change the current working directory to the specified path.
    *
    * Throws `Deno.errors.NotFound` if directory not available.
    */
@@ -289,6 +289,8 @@ declare namespace Deno {
   export const EOF: unique symbol;
   export type EOF = typeof EOF;
 
+  // @url js/io.d.ts
+
   /** **UNSTABLE**: might remove `"SEEK_"` prefix. Might not use all-caps. */
   export enum SeekMode {
     SEEK_START = 0,
@@ -298,15 +300,15 @@ declare namespace Deno {
 
   /** **UNSTABLE**: might make `Reader` into iterator of some sort. */
   export interface Reader {
-    /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number
-     * of bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error
-     * encountered. Even if `read()` returns `n` < `p.byteLength`, it may use
-     * all of `p` as scratch space during the call. If some data is available
-     * but not `p.byteLength` bytes, `read()` conventionally returns what is
-     * available instead of waiting for more.
+    /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number of
+     * bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error
+     * encountered. Even if `read()` resolves to `n` < `p.byteLength`, it may
+     * use all of `p` as scratch space during the call. If some data is
+     * available but not `p.byteLength` bytes, `read()` conventionally resolves
+     * to what is available instead of waiting for more.
      *
-     * When `read()` encounters end-of-file condition, it returns `Deno.EOF`
-     * symbol.
+     * When `read()` encounters end-of-file condition, it resolves to
+     * `Deno.EOF` symbol.
      *
      * When `read()` encounters an error, it rejects with an error.
      *
@@ -342,12 +344,12 @@ declare namespace Deno {
   }
 
   export interface Writer {
-    /** Writes `p.byteLength` bytes from `p` to the underlying data
-     * stream. It resolves with the number of bytes written from `p` (`0` <= `n`
-     * <= `p.byteLength`) or reject with the error encountered that caused the
-     * write to stop early. `write()` must reject with a non-null error if it
-     * returns `n` < `p.byteLength`. `write()` must not modify the slice data,
-     * even temporarily.
+    /** Writes `p.byteLength` bytes from `p` to the underlying data stream. It
+     * resolves to the number of bytes written from `p` (`0` <= `n` <=
+     * `p.byteLength`) or reject with the error encountered that caused the
+     * write to stop early. `write()` must reject with a non-null error if
+     * would resolve to `n` < `p.byteLength`. `write()` must not modify the
+     * slice data, even temporarily.
      *
      * Implementations should not retain a reference to `p`.
      */
@@ -373,10 +375,10 @@ declare namespace Deno {
 
   export interface Seeker {
     /** Seek sets the offset for the next `read()` or `write()` to offset,
-     * interpreted according to `whence`: `SeekStart` means relative to the
-     * start of the file, `SeekCurrent` means relative to the current offset,
-     * and `SeekEnd` means relative to the end. Seek returns the new offset
-     * relative to the start of the file and an error, if any.
+     * interpreted according to `whence`: `SEEK_START` means relative to the
+     * start of the file, `SEEK_CURRENT` means relative to the current offset,
+     * and `SEEK_END` means relative to the end. Seek resolves to the new offset
+     * relative to the start of the file.
      *
      * Seeking to an offset before the start of the file is an error. Seeking to
      * any positive offset is legal, but the behavior of subsequent I/O
@@ -387,10 +389,9 @@ declare namespace Deno {
 
   export interface SyncSeeker {
     /** Seek sets the offset for the next `readSync()` or `writeSync()` to
-     * offset, interpreted according to `whence`: `SeekStart` means relative to
-     * the start of the file, `SeekCurrent` means relative to the current
-     * offset, and `SeekEnd` means relative to the end. Seek returns the new
-     * offset relative to the start of the file and an error, if any.
+     * offset, interpreted according to `whence`: `SEEK_START` means relative
+     * to the start of the file, `SEEK_CURRENT` means relative to the current
+     * offset, and `SEEK_END` means relative to the end.
      *
      * Seeking to an offset before the start of the file is an error. Seeking to
      * any positive offset is legal, but the behavior of subsequent I/O
@@ -407,8 +408,8 @@ declare namespace Deno {
   export interface ReadWriteSeeker extends Reader, Writer, Seeker {}
 
   /** Copies from `src` to `dst` until either `EOF` is reached on `src` or an
-   * error occurs. It returns the number of bytes copied and the first error
-   * encountered while copying, if any.
+   * error occurs. It resolves to the number of bytes copied or rejects with
+   * the first error encountered while copying.
    *
    * Because `copy()` is defined to read from `src` until `EOF`, it does not
    * treat an `EOF` from `read()` as an error to be reported.
@@ -425,7 +426,7 @@ declare namespace Deno {
 
   // @url js/files.d.ts
 
-  /** Open a file and return an instance of the `File` object synchronously.
+  /** Synchronously open a file and return an instance of the `File` object.
    *
    *       const file = Deno.openSync("/foo/bar.txt", { read: true, write: true });
    *
@@ -433,7 +434,7 @@ declare namespace Deno {
    */
   export function openSync(filename: string, options?: OpenOptions): File;
 
-  /** Open a file and return an instance of the `File` object synchronously.
+  /** Synchronously open a file and return an instance of the `File` object.
    *
    *       const file = Deno.openSync("/foo/bar.txt", "r");
    *
@@ -441,7 +442,7 @@ declare namespace Deno {
    */
   export function openSync(filename: string, mode?: OpenMode): File;
 
-  /** Open a file and return an instance of the `File` object.
+  /** Open a file and resolve to an instance of the `File` object.
    *
    *     const file = await Deno.open("/foo/bar.txt", { read: true, write: true });
    *
@@ -449,7 +450,7 @@ declare namespace Deno {
    */
   export function open(filename: string, options?: OpenOptions): Promise<File>;
 
-  /** Open a file and resolves with an instance of `Deno.File`.
+  /** Open a file and resolves to an instance of `Deno.File`.
    *
    *     const file = await Deno.open("/foo/bar.txt, "w+");
    *
@@ -466,7 +467,7 @@ declare namespace Deno {
    */
   export function createSync(filename: string): File;
 
-  /** Creates a file if none exists or truncates an existing file and returns
+  /** Creates a file if none exists or truncates an existing file and resolves to
    *  an instance of `Deno.File`.
    *
    *       const file = await Deno.create("/foo/bar.txt");
@@ -475,21 +476,20 @@ declare namespace Deno {
    */
   export function create(filename: string): Promise<File>;
 
-  /** Read synchronously from a file ID into an array buffer.
+  /** Synchronously read from a file ID into an array buffer.
    *
-   * Return `number | EOF` for the operation.
+   * Returns `number | EOF` for the operation.
    *
    *      const file = Deno.openSync("/foo/bar.txt");
    *      const buf = new Uint8Array(100);
    *      const nread = Deno.readSync(file.rid, buf);
    *      const text = new TextDecoder().decode(buf);
-   *
    */
   export function readSync(rid: number, p: Uint8Array): number | EOF;
 
   /** Read from a resource ID into an array buffer.
    *
-   * Resolves with the `number | EOF` for the operation.
+   * Resolves to the `number | EOF` for the operation.
    *
    *       const file = await Deno.open("/foo/bar.txt");
    *       const buf = new Uint8Array(100);
@@ -498,9 +498,9 @@ declare namespace Deno {
    */
   export function read(rid: number, p: Uint8Array): Promise<number | EOF>;
 
-  /** Write synchronously to the resource ID the contents of the array buffer.
+  /** Synchronously write to the resource ID the contents of the array buffer.
    *
-   * Resolves with the number of bytes written.
+   * Resolves to the number of bytes written.
    *
    *       const encoder = new TextEncoder();
    *       const data = encoder.encode("Hello world\n");
@@ -511,17 +511,16 @@ declare namespace Deno {
 
   /** Write to the resource ID the contents of the array buffer.
    *
-   * Resolves with the number of bytes written.
+   * Resolves to the number of bytes written.
    *
    *      const encoder = new TextEncoder();
    *      const data = encoder.encode("Hello world\n");
    *      const file = await Deno.open("/foo/bar.txt");
    *      await Deno.write(file.rid, data);
-   *
    */
   export function write(rid: number, p: Uint8Array): Promise<number>;
 
-  /** Seek a file ID synchronously to the given offset under mode given by `whence`.
+  /** Synchronously seek a file ID to the given offset under mode given by `whence`.
    *
    *       const file = Deno.openSync("/foo/bar.txt");
    *       Deno.seekSync(file.rid, 0, 0);
@@ -530,10 +529,8 @@ declare namespace Deno {
 
   /** Seek a file ID to the given offset under mode given by `whence`.
    *
-   *      (async () => {
-   *        const file = await Deno.open("/foo/bar.txt");
-   *        await Deno.seek(file.rid, 0, 0);
-   *      })();
+   *      const file = await Deno.open("/foo/bar.txt");
+   *      await Deno.seek(file.rid, 0, 0);
    */
   export function seek(
     rid: number,
@@ -573,49 +570,32 @@ declare namespace Deno {
   export const stderr: File;
 
   export interface OpenOptions {
-    /** Sets the option for read access.
-     *
-     * This option, when `true`, will indicate that the file should be readable
-     * if opened. */
+    /** Sets the option for read access. This option, when `true`, means that the
+     * file should be read-able if opened. */
     read?: boolean;
-    /** Sets the option for write access.
-     *
-     * This option, when `true`, will indicate that the file should be
-     * writeable if opened.
-     *
-     * If the file already exists, any write calls on it will overwrite
-     * its contents, without truncating it. */
+    /** 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. */
     write?: boolean;
-    /** Sets the option for creating a new file.
-     *
-     * This option indicates whether a new file will be created if the file does
-     * not yet already exist.
-     *
-     * In order for the file to be created, write or append access must be
-     * used. */
-    create?: boolean;
-    /** 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` length if it already exists.
-     *
-     * The file must be opened with write access for truncate to work. */
-    truncate?: boolean;
-    /** Sets the option for the append mode.
-     *
-     * This option, when `true`, means that writes will append to a file instead
-     * of overwriting previous contents.
-     *
+    /**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 }`. */
     append?: boolean;
-    /** Sets the option to always create a new file.
-     *
-     * This option indicates whether a new file will be created. No file is
-     * allowed to exist at the target location, also no (dangling) symlink.
-     *
-     * If `{ createNew: true }` is set, `create` and `truncate` value are
-     * ignored. */
+    /** 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`
+     * length if it already exists. The file must be opened with write access
+     * for truncate to work. */
+    truncate?: boolean;
+    /** 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. */
+    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. */
     createNew?: boolean;
   }
 
@@ -681,7 +661,7 @@ declare namespace Deno {
      * the total space allocated for the buffer's data. */
     readonly capacity: number;
     /** Discards all but the first `n` unread bytes from the buffer but
-     * continues to use the same allocated storage.  It throws if `n` is
+     * continues to use the same allocated storage. It throws if `n` is
      * negative or greater than the length of the buffer. */
     truncate(n: number): void;
     /** Resets the buffer to be empty, but it retains the underlying storage for
@@ -692,8 +672,8 @@ declare namespace Deno {
      * return, the return is `Deno.EOF`. */
     readSync(p: Uint8Array): number | EOF;
     /** Reads the next `p.length` bytes from the buffer or until the buffer is
-     * drained. Resolves with the number of bytes read. If the buffer has no
-     * data to return, resolves with `Deno.EOF`. */
+     * drained. Resolves to the number of bytes read. If the buffer has no
+     * data to return, resolves to `Deno.EOF`. */
     read(p: Uint8Array): Promise<number | EOF>;
     writeSync(p: Uint8Array): number;
     write(p: Uint8Array): Promise<number>;
@@ -706,7 +686,7 @@ declare namespace Deno {
      * [Buffer.Grow](https://golang.org/pkg/bytes/#Buffer.Grow). */
     grow(n: number): void;
     /** Reads data from `r` until `Deno.EOF` and appends it to the buffer,
-     * growing the buffer as needed. It resolves with the number of bytes read.
+     * growing the buffer as needed. It resolves to the number of bytes read.
      * If the buffer becomes too large, `.readFrom()` will reject with an error.
      *
      * Based on Go Lang's
@@ -721,7 +701,7 @@ declare namespace Deno {
     readFromSync(r: SyncReader): number;
   }
 
-  /** Read `r` until `Deno.EOF` and resolves with the content as
+  /** Read `r` until `Deno.EOF` and resolves to the content as
    * `Uint8Array`. */
   export function readAll(r: Reader): Promise<Uint8Array>;
 
@@ -731,31 +711,30 @@ declare namespace Deno {
   /** Write all the content of `arr` to `w`. */
   export function writeAll(w: Writer, arr: Uint8Array): Promise<void>;
 
-  /** Write synchronously all the content of `arr` to `w`. */
+  /** Synchronously write all the content of `arr` to `w`. */
   export function writeAllSync(w: SyncWriter, arr: Uint8Array): void;
 
+  // @url js/mkdir.d.ts
+
   export interface MkdirOption {
-    /** If set to `true`, nested directories will be created (also known as
-     * `mkdir -p`) */
+    /** Defaults to `false`. 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. */
     recursive?: boolean;
-    /** Sets permission bits (before `umask`) on Linux/Mac OS and does nothing
-     * on Windows */
+    /** Permissions to use when creating the directory (defaults to `0o777`,
+     * before the process's umask).
+     * Does nothing/raises on Windows. */
     mode?: number;
   }
 
-  /** Creates a new directory with the specified path synchronously.
-   *
-   * If `recursive` is set to `true`, nested directories will be created (also
-   * known as `mkdir -p`).
-   *
-   * `mode` sets permission bits (before `umask`) on Linux/Mac OS and does
-   * nothing on Windows.
+  /** Synchronously creates a new directory with the specified path.
    *
    *       Deno.mkdirSync("new_dir");
    *       Deno.mkdirSync("nested/directories", { recursive: true });
    *
-   * Requires `allow-write` permission.
-   */
+   * Requires `allow-write` permission. */
   export function mkdirSync(path: string, options?: MkdirOption): void;
 
   /** @deprecated */
@@ -767,17 +746,10 @@ declare namespace Deno {
 
   /** Creates a new directory with the specified path.
    *
-   * If `recursive` is set to `true`, nested directories will be created (also
-   * known as `mkdir -p`).
-   *
-   * `mode` sets permission bits (before `umask`) on Linux/Mac OS and does
-   * nothing on Windows.
-   *
    *       await Deno.mkdir("new_dir");
    *       await Deno.mkdir("nested/directories", { recursive: true });
    *
-   * Requires `allow-write` permission.
-   */
+   * Requires `allow-write` permission. */
   export function mkdir(path: string, options?: MkdirOption): Promise<void>;
 
   /** @deprecated */
@@ -790,83 +762,87 @@ declare namespace Deno {
   // @url js/make_temp.d.ts
 
   export interface MakeTempOptions {
+    /** Directory where the temporary directory should be created (defaults to
+     * the env variable TMPDIR, or the system's default, usually /tmp). */
     dir?: string;
+    /** String that should precede the random portion of the temporary
+     * directory's name. */
     prefix?: string;
+    /** String that should follow the random portion of the temporary
+     * directory's name. */
     suffix?: string;
   }
 
-  /** Creates a new temporary directory in the directory `dir`, its name
-   * beginning with `prefix` and ending with `suffix`.
+  /** Synchronously creates a new temporary directory in the directory `dir`,
+   * its name beginning with `prefix` and ending with `suffix`.
    *
    * It returns the full path to the newly created directory.
    *
-   * If `dir` is unspecified, it uses the default directory for temporary files.
-   * Multiple programs calling simultaneously will not choose the same
-   * directory. It is the caller's responsibility to remove the directory
-   * when no longer needed.
+   * If `dir` is unspecified, uses the default directory for temporary files.
+   * Multiple programs calling this function simultaneously will create different
+   * directories. It is the caller's responsibility to remove the directory when
+   * no longer needed.
    *
    *       const tempDirName0 = Deno.makeTempDirSync();
    *       const tempDirName1 = Deno.makeTempDirSync({ prefix: 'my_temp' });
    *
-   * Requires `allow-write` permission.
-   */
+   * Requires `allow-write` permission. */
   // TODO(ry) Doesn't check permissions.
   export function makeTempDirSync(options?: MakeTempOptions): string;
 
   /** Creates a new temporary directory in the directory `dir`, its name
    * beginning with `prefix` and ending with `suffix`.
    *
-   * It resolves with the full path to the newly created directory.
+   * It resolves to the full path to the newly created directory.
    *
-   * If `dir` is unspecified, it uses the default directory for temporary files.
-   * Multiple programs calling simultaneously will not choose the same
-   * directory. It is the caller's responsibility to remove the directory
-   * when no longer needed.
+   * If `dir` is unspecified, uses the default directory for temporary files.
+   * Multiple programs calling this function simultaneously will create different
+   * directories. It is the caller's responsibility to remove the directory when
+   * no longer needed.
    *
    *       const tempDirName0 = await Deno.makeTempDir();
    *       const tempDirName1 = await Deno.makeTempDir({ prefix: 'my_temp' });
    *
-   * Requires `allow-write` permission.
-   */
+   * Requires `allow-write` permission. */
   // TODO(ry) Doesn't check permissions.
   export function makeTempDir(options?: MakeTempOptions): Promise<string>;
 
-  /** Creates a new temporary file in the directory `dir`, its name beginning
-   * with `prefix` and ending with `suffix`.
+  /** Synchronously creates a new temporary file in the directory `dir`, its name
+   * beginning with `prefix` and ending with `suffix`.
    *
-   * It resolves with the full path to the newly created file.
+   * It returns the full path to the newly created file.
    *
-   * If `dir` is unspecified, it uses the default directory for temporary files.
-   * Multiple programs calling simultaneously will not choose the same
-   * directory. It is the caller's responsibility to remove the file when no
-   * longer needed.
+   * If `dir` is unspecified, uses the default directory for temporary files.
+   * Multiple programs calling this function simultaneously will create different
+   * files. It is the caller's responsibility to remove the file when
+   * no longer needed.
    *
    *       const tempFileName0 = Deno.makeTempFileSync();
    *       const tempFileName1 = Deno.makeTempFileSync({ prefix: 'my_temp' });
    *
-   * Requires `allow-write` permission.
-   */
+   * Requires `allow-write` permission. */
   export function makeTempFileSync(options?: MakeTempOptions): string;
 
-  /** Creates a new temporary file in the directory `dir`, its name beginning
-   * with `prefix` and ending with `suffix`.
+  /** Creates a new temporary file in the directory `dir`, its name
+   * beginning with `prefix` and ending with `suffix`.
    *
-   * It resolves with the full path to the newly created file.
+   * It resolves to the full path to the newly created file.
    *
-   * If `dir` is unspecified, it uses the default directory for temporary files.
-   * Multiple programs calling simultaneously will not choose the same
-   * directory. It is the caller's responsibility to remove the file when no
-   * longer needed.
+   * If `dir` is unspecified, uses the default directory for temporary files.
+   * Multiple programs calling this function simultaneously will create different
+   * files. It is the caller's responsibility to remove the file when
+   * no longer needed.
    *
    *       const tempFileName0 = await Deno.makeTempFile();
    *       const tempFileName1 = await Deno.makeTempFile({ prefix: 'my_temp' });
    *
-   * Requires `allow-write` permission.
-   */
+   * Requires `allow-write` permission. */
   export function makeTempFile(options?: MakeTempOptions): Promise<string>;
 
-  /** Changes the permission of a specific file/directory of specified path
-   * synchronously.
+  // @url js/chmod.d.ts
+
+  /** Synchronously changes the permission of a specific file/directory of
+   * specified path.  Ignores the process's umask.
    *
    *       Deno.chmodSync("/path/to/file", 0o666);
    *
@@ -874,14 +850,16 @@ declare namespace Deno {
   export function chmodSync(path: string, mode: number): void;
 
   /** Changes the permission of a specific file/directory of specified path.
+   * Ignores the process's umask.
    *
    *       await Deno.chmod("/path/to/file", 0o666);
    *
-   * Requires `allow-write` permission.
-   */
+   * Requires `allow-write` permission. */
   export function chmod(path: string, mode: number): Promise<void>;
 
-  /** Change owner of a regular file or directory synchronously. Linux/Mac OS
+  // @url js/chown.d.ts
+
+  /** Synchronously change owner of a regular file or directory. Linux/Mac OS
    * only at the moment.
    *
    * Requires `allow-write` permission.
@@ -892,8 +870,8 @@ declare namespace Deno {
    */
   export function chownSync(path: string, uid: number, gid: number): void;
 
-  /** Change owner of a regular file or directory asynchronously. Linux/Mac OS
-   * only at the moment.
+  /** Change owner of a regular file or directory. Linux/Mac OS only at the
+   * moment.
    *
    * Requires `allow-write` permission.
    *
@@ -903,6 +881,8 @@ declare namespace Deno {
    */
   export function chown(path: string, uid: number, gid: number): Promise<void>;
 
+  // @url js/utime.d.ts
+
   /** **UNSTABLE**: needs investigation into high precision time.
    *
    * Synchronously changes the access and modification times of a file system
@@ -911,8 +891,7 @@ declare namespace Deno {
    *
    *       Deno.utimeSync("myfile.txt", 1556495550, new Date());
    *
-   * Requires `allow-write` permission.
-   */
+   * Requires `allow-write` permission. */
   export function utimeSync(
     filename: string,
     atime: number | Date,
@@ -934,33 +913,35 @@ declare namespace Deno {
     mtime: number | Date
   ): Promise<void>;
 
-  /** **UNSTABLE**: rename to RemoveOptions */
+  // @url js/remove.d.ts
+
+  /** UNSTABLE: rename to RemoveOptions */
   export interface RemoveOption {
+    /** Defaults to `false`. If set to `true`, path will be removed even if
+     * it's a non-empty directory. */
     recursive?: boolean;
   }
 
-  /** Removes the named file or directory synchronously. Would throw an error if
-   * permission denied, not found, or directory not empty if `recursive` set to
-   * `false`.
-   *
-   * `recursive` defaults to `false`.
+  /** Synchronously removes the named file or directory. Throws error if
+   * permission denied, path not found, or path is a non-empty directory and
+   * the `recursive` option isn't set to `true`.
    *
-   *       Deno.removeSync("/path/to/dir/or/file", {recursive: false});
+   *       Deno.removeSync("/path/to/dir/or/file", { recursive: false });
    *
    * Requires `allow-write` permission. */
   export function removeSync(path: string, options?: RemoveOption): void;
 
-  /** Removes the named file or directory. Would throw error if
-   * permission denied, not found, or directory not empty if `recursive` set
-   * to false.
+  /** Removes the named file or directory. Throws error if permission denied,
+   * path not found, or path is a non-empty directory and the `recursive`
+   * option isn't set to `true`.
    *
-   * `recursive` defaults to `false`.
-   *
-   *       await Deno.remove("/path/to/dir/or/file", {recursive: false});
+   *       await Deno.remove("/path/to/dir/or/file", { recursive: false });
    *
    * Requires `allow-write` permission. */
   export function remove(path: string, options?: RemoveOption): Promise<void>;
 
+  // @url js/rename.d.ts
+
   /** Synchronously renames (moves) `oldpath` to `newpath`. If `newpath` already
    * exists and is not a directory, `renameSync()` replaces it. OS-specific
    * restrictions may apply when `oldpath` and `newpath` are in different
@@ -991,7 +972,7 @@ declare namespace Deno {
    * Requires `allow-read` permission. */
   export function readFileSync(filename: string): Uint8Array;
 
-  /** Reads and resolves with the entire contents of a file.
+  /** Reads and resolves to the entire contents of a file.
    *
    *       const decoder = new TextDecoder("utf-8");
    *       const data = await Deno.readFile("hello.txt");
@@ -1000,11 +981,13 @@ declare namespace Deno {
    * Requires `allow-read` permission. */
   export function readFile(filename: string): Promise<Uint8Array>;
 
-  /** **UNSTABLE**: `.len` maybe should be `.length` or `.size`.
+  // @url js/file_info.d.ts
+
+  /** UNSTABLE: 'len' maybe should be 'length' or 'size'.
    *
-   * A FileInfo describes a file and is returned by `stat`, `lstat`, `statSync`,
-   * `lstatSync`.
-   */
+   * A FileInfo describes a file and is returned by `stat`, `lstat`,
+   * `statSync`, `lstatSync`. A list of FileInfo is returned by `readDir`,
+   * `readDirSync`. */
   export interface FileInfo {
     /** **UNSTABLE**: `.len` maybe should be `.length` or `.size`.
      *
@@ -1014,13 +997,13 @@ declare namespace Deno {
      * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This
      * may not be available on all platforms. */
     modified: number | null;
-    /** The last access time of the file. This corresponds to the `atime` field
-     * from `stat` on Linux/Mac OS and `ftLastAccessTime` on Windows. This may
-     * not be available on all platforms. */
+    /** The last access time of the file. This corresponds to the `atime`
+     * field from `stat` on Unix and `ftLastAccessTime` on Windows. This may not
+     * be available on all platforms. */
     accessed: number | null;
     /** The last access time of the file. This corresponds to the `birthtime`
-     * field from `stat` on Linux/Mac OS and `ftCreationTime` on Windows. This
-     * may not be available on all platforms. */
+     * field from `stat` on Mac/BSD and `ftCreationTime` on Windows. This may not
+     * be available on all platforms. */
     created: number | null;
     /** The file or directory name. */
     name: string | null;
@@ -1081,16 +1064,19 @@ declare namespace Deno {
    * Requires `allow-read` permission. */
   export function realpathSync(path: string): string;
 
-  /** Resolves with the absolute normalized path, with symbolic links resolved.
+  /** Resolves to the absolute normalized path, with symbolic links resolved.
    *
    *       const realPath = await Deno.realpath("./some/path");
    *
    * Requires `allow-read` permission. */
   export function realpath(path: string): Promise<string>;
 
-  /** **UNSTABLE**: Possibly rename to `readdirSync()`.
+  // @url js/read_dir.d.ts
+
+  /** UNSTABLE: Unstable rename to readdirSync.
    *
-   * Reads the directory given by path and returns an array of `Deno.FileInfo`.
+  /* Synchronously reads the directory given by `path` and returns an array of
+   * `Deno.FileInfo`.
    *
    *       const files = Deno.readDirSync("/");
    *
@@ -1100,38 +1086,34 @@ declare namespace Deno {
   /** UNSTABLE: Possibly rename to `.readdir()`. Maybe need to return an
    * `AsyncIterable`.
    *
-   * Reads the directory given by path and resolves with an array of
-   * `Deno.FileInfo`.
+   * Reads the directory given by `path` and resolves to an array of `Deno.FileInfo`.
    *
    *       const files = await Deno.readDir("/");
    *
-   * Requires `allow-read` permission.
-   */
+   * Requires `allow-read` permission. */
   export function readDir(path: string): Promise<FileInfo[]>;
 
-  /** Copies the contents of a file to another by name.
-   *
-   * Creates a new file if target does not exists, and if target exists,
-   * overwrites original content of the target file.
-   *
-   * It will also copy the permissions of the original file to the destination.
+  // @url js/copy_file.d.ts
+
+  /** Synchronously copies the contents and permissions of one file to another
+   * specified path, by default creating a new file if needed, else overwriting.
+   * Fails if target path is a directory or is unwritable.
    *
    *       Deno.copyFileSync("from.txt", "to.txt");
    *
-   * Requires `allow-read` and `allow-write` permissions. */
-  export function copyFileSync(from: string, to: string): void;
+   * Requires `allow-read` permission on fromPath.
+   * Requires `allow-write` permission on toPath. */
+  export function copyFileSync(fromPath: string, toPath: string): void;
 
-  /** Copies the contents of a file to another by name.
-   *
-   * Creates a new file if target does not exists, and if target exists,
-   * overwrites original content of the target file.
-   *
-   * It will also copy the permissions of the original file to the destination.
+  /** Copies the contents and permissions of one file to another specified path,
+   * by default creating a new file if needed, else overwriting. Fails if target
+   * path is a directory or is unwritable.
    *
    *       await Deno.copyFile("from.txt", "to.txt");
    *
-   * Requires `allow-read` and `allow-write` permissions. */
-  export function copyFile(from: string, to: string): Promise<void>;
+   * Requires `allow-read` permission on fromPath.
+   * Requires `allow-write` permission on toPath. */
+  export function copyFile(fromPath: string, toPath: string): Promise<void>;
 
   // @url js/read_link.d.ts
 
@@ -1142,15 +1124,17 @@ declare namespace Deno {
    * Requires `allow-read` permission. */
   export function readlinkSync(name: string): string;
 
-  /** Resolves with the destination of the named symbolic link.
+  /** Resolves to the destination of the named symbolic link.
    *
    *       const targetPath = await Deno.readlink("symlink/path");
    *
    * Requires `allow-read` permission. */
   export function readlink(name: string): Promise<string>;
 
-  /** Resolves with the `FileInfo` for the `filename` provided. If the given
-   * `filename` is a symlink, information about the symlink will be returned.
+  // @url js/stat.d.ts
+
+  /** Resolves to a `Deno.FileInfo` for the specified path. If path is a
+   * symlink, information for the symlink will be returned.
    *
    *       const fileInfo = await Deno.lstat("hello.txt");
    *       assert(fileInfo.isFile());
@@ -1158,8 +1142,8 @@ declare namespace Deno {
    * Requires `allow-read` permission. */
   export function lstat(filename: string): Promise<FileInfo>;
 
-  /** Returns the `FileInfo` for the `filename` provided. If the given
-   * `filename` is a symlink, information about the symlink will be returned.
+  /** Synchronously returns a `Deno.FileInfo` for the specified path. If
+   * path is a symlink, information for the symlink will be returned.
    *
    *       const fileInfo = Deno.lstatSync("hello.txt");
    *       assert(fileInfo.isFile());
@@ -1167,8 +1151,8 @@ declare namespace Deno {
    * Requires `allow-read` permission. */
   export function lstatSync(filename: string): FileInfo;
 
-  /** Resolves with the `FileInfo` for the `filename` provided. Will always
-   * resolve and follow symlinks.
+  /** Resolves to a `Deno.FileInfo` for the specified path. Will always follow
+   * symlinks.
    *
    *       const fileInfo = await Deno.stat("hello.txt");
    *       assert(fileInfo.isFile());
@@ -1176,8 +1160,8 @@ declare namespace Deno {
    * Requires `allow-read` permission. */
   export function stat(filename: string): Promise<FileInfo>;
 
-  /** Returns the `FileInfo` for the `filename` provided. Will always resolve
-   * and follow symlinks.
+  /** Synchronously returns a `Deno.FileInfo` for the specified path. Will
+   * always follow symlinks.
    *
    *       const fileInfo = Deno.statSync("hello.txt");
    *       assert(fileInfo.isFile());
@@ -1185,6 +1169,8 @@ declare namespace Deno {
    * Requires `allow-read` permission. */
   export function statSync(filename: string): FileInfo;
 
+  // @url js/link.d.ts
+
   /** Creates `newname` as a hard link to `oldname`.
    *
    *       Deno.linkSync("old/name", "new/name");
@@ -1199,6 +1185,8 @@ declare namespace Deno {
    * Requires `allow-read` and `allow-write` permissions. */
   export function link(oldname: string, newname: string): Promise<void>;
 
+  // @url js/symlink.d.ts
+
   /** **UNSTABLE**: `type` argument type may be changed to `"dir" | "file"`.
    *
    * Creates `newname` as a symbolic link to `oldname`. The type argument can be
@@ -1214,7 +1202,7 @@ declare namespace Deno {
     type?: string
   ): void;
 
-  /** UNSTABLE type argument may be changed to "dir" | "file"
+  /** **UNSTABLE**: `type` argument may be changed to "dir" | "file"
    *
    * Creates `newname` as a symbolic link to `oldname`. The type argument can be
    * set to `dir` or `file`. Is only available on Windows and ignored on other
@@ -1229,23 +1217,28 @@ declare namespace Deno {
     type?: string
   ): Promise<void>;
 
+  // @url js/write_file.d.ts
+
   /** Options for writing to a file. */
   export interface WriteFileOptions {
-    /** Change the file's permissions. */
-    perm?: number;
-    /** Create the file if it does not exist.  Defaults to `true`. */
-    create?: boolean;
-    /** Append to the file.  Defaults to `false`. */
+    /** Defaults to `false`. If set to `true`, will append to a file instead of
+     * overwriting previous contents. */
     append?: boolean;
+    /** Sets the option to allow creating a new file, if one doesn't already
+     * exist at the specified path (defaults to `true`). */
+    create?: boolean;
+    /** Permissions always applied to file. */
+    perm?: number;
   }
 
-  /** Write a new file, with given `filename` and `data`.
+  /** Synchronously write data to the given path, by default creating a new
+   * file if needed, else overwriting.
    *
    *       const encoder = new TextEncoder();
    *       const data = encoder.encode("Hello world\n");
    *       Deno.writeFileSync("hello.txt", data);
    *
-   * Requires `allow-write` and `allow-read` permissions if create is `false`.
+   * Requires `allow-write` permission, and `allow-read` if create is `false`.
    */
   export function writeFileSync(
     filename: string,
@@ -1253,13 +1246,14 @@ declare namespace Deno {
     options?: WriteFileOptions
   ): void;
 
-  /** Write a new file, with given `filename` and `data`.
+  /** Write data to the given path, by default creating a new file if needed,
+   * else overwriting.
    *
    *       const encoder = new TextEncoder();
    *       const data = encoder.encode("Hello world\n");
    *       await Deno.writeFile("hello.txt", data);
    *
-   * Requires `allow-write` and `allow-read` permissions if create is `false`.
+   * Requires `allow-write` permission, and `allow-read` if create is `false`.
    */
   export function writeFile(
     filename: string,
@@ -1272,9 +1266,9 @@ declare namespace Deno {
     /** The full url for the module, e.g. `file://some/file.ts` or
      * `https://some/file.ts`. */
     filename: string;
-    /** The line number in the file.  It is assumed to be 1-indexed. */
+    /** The line number in the file. It is assumed to be 1-indexed. */
     line: number;
-    /** The column number in the file.  It is assumed to be 1-indexed. */
+    /** The column number in the file. It is assumed to be 1-indexed. */
     column: number;
   }
 
@@ -1284,9 +1278,9 @@ declare namespace Deno {
    * it.
    *
    * When Deno transpiles code, it keep source maps of the transpiled code. This
-   * function can be used to lookup the original location.  This is
+   * function can be used to lookup the original location. This is
    * automatically done when accessing the `.stack` of an error, or when an
-   * uncaught error is logged.  This function can be used to perform the lookup
+   * uncaught error is logged. This function can be used to perform the lookup
    * for creating better error handling.
    *
    * **Note:** `line` and `column` are 1 indexed, which matches display
@@ -1300,7 +1294,6 @@ declare namespace Deno {
    *         column: 15
    *       });
    *       console.log(`${orig.filename}:${orig.line}:${orig.column}`);
-   *
    */
   export function applySourceMap(location: Location): Location;
 
@@ -1384,7 +1377,7 @@ declare namespace Deno {
     | HrtimePermissionDescriptor;
 
   export class Permissions {
-    /** Resolves with the current status of a permission.
+    /** Resolves to the current status of a permission.
      *
      *       const status = await Deno.permissions.query({ name: "read", path: "/etc" });
      *       if (status.state === "granted") {
@@ -1393,14 +1386,14 @@ declare namespace Deno {
      */
     query(desc: PermissionDescriptor): Promise<PermissionStatus>;
 
-    /** Revokes a permission, and resolves with the state of the permission.
+    /** Revokes a permission, and resolves to the state of the permission.
      *
      *       const status = await Deno.permissions.revoke({ name: "run" });
      *       assert(status.state !== "granted")
      */
     revoke(desc: PermissionDescriptor): Promise<PermissionStatus>;
 
-    /** Requests the permission, and resolves with the state of the permission.
+    /** Requests the permission, and resolves to the state of the permission.
      *
      *       const status = await Deno.permissions.request({ name: "env" });
      *       if (status.state === "granted") {
@@ -1421,14 +1414,17 @@ declare namespace Deno {
     constructor(state: PermissionState);
   }
 
-  /** Truncates or extends the specified `name`, to reach the specified `len`.
+  // @url js/truncate.d.ts
+
+  /** Synchronously truncates or extends the specified file, to reach the
+   * specified `len`.
    *
    *       Deno.truncateSync("hello.txt", 10);
    *
    * Requires `allow-write` permission. */
   export function truncateSync(name: string, len?: number): void;
 
-  /** Truncates or extends the specified `name`, to reach the specified `len`.
+  /** Truncates or extends the specified file, to reach the specified `len`.
    *
    *       await Deno.truncate("hello.txt", 10);
    *
@@ -1462,7 +1458,7 @@ declare namespace Deno {
    *        const response = some_op.dispatch(new Uint8Array([1,2,3,4]));
    *        console.log(`Response from plugin ${response}`);
    *
-   * Requires the `allow-plugin` permission. */
+   * Requires `allow-plugin` permission. */
   export function openPlugin(filename: string): Plugin;
 
   export type Transport = "tcp" | "udp";
@@ -1508,7 +1504,7 @@ declare namespace Deno {
    * Waits for the next message to the passed `rid` and writes it on the passed
    * `Uint8Array`.
    *
-   * Resolves with the number of bytes written and the remote address. */
+   * Resolves to the number of bytes written and the remote address. */
   export function recvfrom(rid: number, p: Uint8Array): Promise<[number, Addr]>;
 
   /** **UNSTABLE**: new API, yet to be vetted.
@@ -1749,7 +1745,7 @@ declare namespace Deno {
     readonly stdin?: WriteCloser;
     readonly stdout?: ReadCloser;
     readonly stderr?: ReadCloser;
-    /** Resolves with the current status of the process. */
+    /** Resolves to the current status of the process. */
     status(): Promise<ProcessStatus>;
     /** Buffer the stdout and return it as `Uint8Array` after `Deno.EOF`.
      *
@@ -1934,7 +1930,7 @@ declare namespace Deno {
     message: string;
     /** An ordered array of further diagnostics. */
     messageChain?: DiagnosticMessageChain;
-    /** Information related to the diagnostic.  This is present when there is a
+    /** Information related to the diagnostic. This is present when there is a
      * suggestion or other additional diagnostic information */
     relatedInformation?: DiagnosticItem[];
     /** The text of the source line related to the diagnostic. */
@@ -2002,7 +1998,7 @@ declare namespace Deno {
      * `false`. */
     declarationMap?: boolean;
     /** Provide full support for iterables in `for..of`, spread and
-     * destructuring when targeting ES5 or ES3.  Defaults to `false`. */
+     * destructuring when targeting ES5 or ES3. Defaults to `false`. */
     downlevelIteration?: boolean;
     /** Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files.
      * Defaults to `false`. */
@@ -2040,7 +2036,7 @@ declare namespace Deno {
     /** Emit class fields with ECMAScript-standard semantics. Defaults to `false`.
      * Does not apply to `"esnext"` target. */
     useDefineForClassFields?: boolean;
-    /** List of library files to be included in the compilation.  If omitted,
+    /** List of library files to be included in the compilation. If omitted,
      * then the Deno main runtime libs are used. */
     lib?: string[];
     /** The locale to use to show error messages. */
@@ -2051,7 +2047,7 @@ declare namespace Deno {
      * specified will be embedded in the source map to direct the debugger where
      * the map files will be located. Defaults to `undefined`. */
     mapRoot?: string;
-    /** Specify the module format for the emitted code.  Defaults to
+    /** Specify the module format for the emitted code. Defaults to
      * `"esnext"`. */
     module?:
       | "none"
@@ -2091,7 +2087,7 @@ declare namespace Deno {
     /** Report errors on unused parameters. Defaults to `false`. */
     noUnusedParameters?: boolean;
     /** Redirect output structure to the directory. This only impacts
-     * `Deno.compile` and only changes the emitted file names.  Defaults to
+     * `Deno.compile` and only changes the emitted file names. Defaults to
      * `undefined`. */
     outDir?: string;
     /** List of path mapping entries for module names to locations relative to the
@@ -2159,8 +2155,8 @@ declare namespace Deno {
     /** List of names of type definitions to include. Defaults to `undefined`.
      *
      * The type definitions are resolved according to the normal Deno resolution
-     * irrespective of if sources are provided on the call.  Like other Deno
-     * modules, there is no "magical" resolution.  For example:
+     * irrespective of if sources are provided on the call. Like other Deno
+     * modules, there is no "magical" resolution. For example:
      *
      *      Deno.compile(
      *        "./foo.js",
@@ -2169,7 +2165,6 @@ declare namespace Deno {
      *          types: [ "./foo.d.ts", "https://deno.land/x/example/types.d.ts" ]
      *        }
      *      );
-     *
      */
     types?: string[];
   }
@@ -2185,7 +2180,7 @@ declare namespace Deno {
 
   /** **UNSTABLE**: new API, yet to be vetted.
    *
-   * Takes a set of TypeScript sources and resolves with a map where the key was
+   * Takes a set of TypeScript sources and resolves to a map where the key was
    * the original file name provided in sources and the result contains the
    * `source` and optionally the `map` from the transpile operation. This does no
    * type checking and validation, it effectively "strips" the types from the
@@ -2196,7 +2191,7 @@ declare namespace Deno {
    *      });
    *
    * @param sources A map where the key is the filename and the value is the text
-   *                to transpile.  The filename is only used in the transpile and
+   *                to transpile. The filename is only used in the transpile and
    *                not resolved, for example to fill in the source name in the
    *                source map.
    * @param options An option object of options to send to the compiler. This is
@@ -2212,11 +2207,11 @@ declare namespace Deno {
   /** **UNSTABLE**: new API, yet to be vetted.
    *
    * Takes a root module name, any optionally a record set of sources. Resolves
-   * with a compiled set of modules.  If just a root name is provided, the modules
+   * with a compiled set of modules. If just a root name is provided, the modules
    * will be resolved as if the root module had been passed on the command line.
    *
    * If sources are passed, all modules will be resolved out of this object, where
-   * the key is the module name and the value is the content.  The extension of
+   * the key is the module name and the value is the content. The extension of
    * the module name will be used to determine the media type of the module.
    *
    *      const [ maybeDiagnostics1, output1 ] = await Deno.compile("foo.ts");
@@ -2227,13 +2222,13 @@ declare namespace Deno {
    *      });
    *
    * @param rootName The root name of the module which will be used as the
-   *                 "starting point".  If no `sources` is specified, Deno will
+   *                 "starting point". If no `sources` is specified, Deno will
    *                 resolve the module externally as if the `rootName` had been
    *                 specified on the command line.
    * @param sources An optional key/value map of sources to be used when resolving
    *                modules, where the key is the module name, and the value is
-   *                the source content.  The extension of the key will determine
-   *                the media type of the file when processing.  If supplied,
+   *                the source content. The extension of the key will determine
+   *                the media type of the file when processing. If supplied,
    *                Deno will not attempt to resolve any modules externally.
    * @param options An optional object of options to send to the compiler. This is
    *                a subset of ts.CompilerOptions which can be supported by Deno.
@@ -2248,7 +2243,7 @@ declare namespace Deno {
    *
    * Takes a root module name, and optionally a record set of sources. Resolves
    * with a single JavaScript string that is like the output of a `deno bundle`
-   * command.  If just a root name is provided, the modules will be resolved as if
+   * command. If just a root name is provided, the modules will be resolved as if
    * the root module had been passed on the command line.
    *
    * If sources are passed, all modules will be resolved out of this object, where
@@ -2263,13 +2258,13 @@ declare namespace Deno {
    *      });
    *
    * @param rootName The root name of the module which will be used as the
-   *                 "starting point".  If no `sources` is specified, Deno will
+   *                 "starting point". If no `sources` is specified, Deno will
    *                 resolve the module externally as if the `rootName` had been
    *                 specified on the command line.
    * @param sources An optional key/value map of sources to be used when resolving
    *                modules, where the key is the module name, and the value is
-   *                the source content.  The extension of the key will determine
-   *                the media type of the file when processing.  If supplied,
+   *                the source content. The extension of the key will determine
+   *                the media type of the file when processing. If supplied,
    *                Deno will not attempt to resolve any modules externally.
    * @param options An optional object of options to send to the compiler. This is
    *                a subset of ts.CompilerOptions which can be supported by Deno.
diff --git a/cli/js/lib.deno.shared_globals.d.ts b/cli/js/lib.deno.shared_globals.d.ts
index acd4c6d25..bec9469c5 100644
--- a/cli/js/lib.deno.shared_globals.d.ts
+++ b/cli/js/lib.deno.shared_globals.d.ts
@@ -1185,14 +1185,14 @@ declare namespace __io {
   }
   export interface Seeker {
     /** Seek sets the offset for the next `read()` or `write()` to offset,
-     * interpreted according to `whence`: `SeekStart` means relative to the start
-     * of the file, `SeekCurrent` means relative to the current offset, and
-     * `SeekEnd` means relative to the end. Seek returns the new offset relative
-     * to the start of the file and an error, if any.
+     * interpreted according to `whence`: `SEEK_START` means relative to the
+     * start of the file, `SEEK_CURRENT` means relative to the current offset,
+     * and `SEEK_END` means relative to the end. Seek returns the new offset
+     * relative to the start of the file and an error, if any.
      *
      * Seeking to an offset before the start of the file is an error. Seeking to
-     * any positive offset is legal, but the behavior of subsequent I/O operations
-     * on the underlying object is implementation-dependent.
+     * any positive offset is legal, but the behavior of subsequent I/O
+     * operations on the underlying object is implementation-dependent.
      */
     seek(offset: number, whence: SeekMode): Promise<void>;
   }
diff --git a/cli/js/link.ts b/cli/js/link.ts
index 4d66d1cf9..cd738b1bc 100644
--- a/cli/js/link.ts
+++ b/cli/js/link.ts
@@ -1,10 +1,11 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "./dispatch_json.ts";
 
-/** Synchronously creates `newname` as a hard link to `oldname`.
+/** Creates `newname` as a hard link to `oldname`.
  *
  *       Deno.linkSync("old/name", "new/name");
- */
+ *
+ * Requires `allow-read` and `allow-write` permissions. */
 export function linkSync(oldname: string, newname: string): void {
   sendSync("op_link", { oldname, newname });
 }
@@ -12,7 +13,8 @@ export function linkSync(oldname: string, newname: string): void {
 /** Creates `newname` as a hard link to `oldname`.
  *
  *       await Deno.link("old/name", "new/name");
- */
+ *
+ * Requires `allow-read` and `allow-write` permissions. */
 export async function link(oldname: string, newname: string): Promise<void> {
   await sendAsync("op_link", { oldname, newname });
 }
diff --git a/cli/js/make_temp.ts b/cli/js/make_temp.ts
index 7b0038388..1d8e283d3 100644
--- a/cli/js/make_temp.ts
+++ b/cli/js/make_temp.ts
@@ -2,57 +2,87 @@
 import { sendSync, sendAsync } from "./dispatch_json.ts";
 
 export interface MakeTempOptions {
+  /** Directory where the temporary directory should be created (defaults to
+   * the env variable TMPDIR, or the system's default, usually /tmp). */
   dir?: string;
+  /** String that should precede the random portion of the temporary
+   * directory's name. */
   prefix?: string;
+  /** String that should follow the random portion of the temporary
+   * directory's name. */
   suffix?: string;
 }
 
-/** makeTempDirSync is the synchronous version of `makeTempDir`.
+/** Synchronously creates a new temporary directory in the directory `dir`,
+ * its name beginning with `prefix` and ending with `suffix`.
+ *
+ * It returns the full path to the newly created directory.
+ *
+ * If `dir` is unspecified, uses the default directory for temporary files.
+ * Multiple programs calling this function simultaneously will create different
+ * directories. It is the caller's responsibility to remove the directory when
+ * no longer needed.
  *
  *       const tempDirName0 = Deno.makeTempDirSync();
  *       const tempDirName1 = Deno.makeTempDirSync({ prefix: 'my_temp' });
- */
+ *
+ * Requires `allow-write` permission. */
 export function makeTempDirSync(options: MakeTempOptions = {}): string {
   return sendSync("op_make_temp_dir", options);
 }
 
-/** makeTempDir creates a new temporary directory in the directory `dir`, its
- * name beginning with `prefix` and ending with `suffix`.
- * It returns the full path to the newly created directory.
- * If `dir` is unspecified, tempDir uses the default directory for temporary
- * files. Multiple programs calling tempDir simultaneously will not choose the
- * same directory. It is the caller's responsibility to remove the directory
- * when no longer needed.
+/** Creates a new temporary directory in the directory `dir`, its name
+ * beginning with `prefix` and ending with `suffix`.
+ *
+ * It resolves to the full path to the newly created directory.
+ *
+ * If `dir` is unspecified, uses the default directory for temporary files.
+ * Multiple programs calling this function simultaneously will create different
+ * directories. It is the caller's responsibility to remove the directory when
+ * no longer needed.
  *
  *       const tempDirName0 = await Deno.makeTempDir();
  *       const tempDirName1 = await Deno.makeTempDir({ prefix: 'my_temp' });
- */
+ *
+ * Requires `allow-write` permission. */
 export async function makeTempDir(
   options: MakeTempOptions = {}
 ): Promise<string> {
   return await sendAsync("op_make_temp_dir", options);
 }
 
-/** makeTempFileSync is the synchronous version of `makeTempFile`.
+/** Synchronously creates a new temporary file in the directory `dir`, its name
+ * beginning with `prefix` and ending with `suffix`.
+ *
+ * It returns the full path to the newly created file.
+ *
+ * If `dir` is unspecified, uses the default directory for temporary files.
+ * Multiple programs calling this function simultaneously will create different
+ * files. It is the caller's responsibility to remove the file when
+ * no longer needed.
  *
  *       const tempFileName0 = Deno.makeTempFileSync();
  *       const tempFileName1 = Deno.makeTempFileSync({ prefix: 'my_temp' });
- */
+ *
+ * Requires `allow-write` permission. */
 export function makeTempFileSync(options: MakeTempOptions = {}): string {
   return sendSync("op_make_temp_file", options);
 }
 
-/** makeTempFile creates a new temporary file in the directory `dir`, its
- * name beginning with `prefix` and ending with `suffix`.
- * It returns the full path to the newly created file.
- * If `dir` is unspecified, tempFile uses the default directory for temporary
- * files. Multiple programs calling tempFile simultaneously will not choose the
- * same directory. It is the caller's responsibility to remove the file
- * when no longer needed.
+/** Creates a new temporary file in the directory `dir`, its name
+ * beginning with `prefix` and ending with `suffix`.
+ *
+ * It resolves to the full path to the newly created file.
+ *
+ * If `dir` is unspecified, uses the default directory for temporary files.
+ * Multiple programs calling this function simultaneously will create different
+ * files. It is the caller's responsibility to remove the file when
+ * no longer needed.
  *
  *       const tempFileName0 = await Deno.makeTempFile();
  *       const tempFileName1 = await Deno.makeTempFile({ prefix: 'my_temp' });
- */
+ *
+ * Requires `allow-write` permission. */
 export async function makeTempFile(
   options: MakeTempOptions = {}
 ): Promise<string> {
diff --git a/cli/js/mkdir.ts b/cli/js/mkdir.ts
index 532d2b73c..ecb15a9c5 100644
--- a/cli/js/mkdir.ts
+++ b/cli/js/mkdir.ts
@@ -26,19 +26,24 @@ function mkdirArgs(
 }
 
 export interface MkdirOption {
+  /** Defaults to `false`. 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. */
   recursive?: boolean;
+  /** Permissions to use when creating the directory (defaults to `0o777`,
+   * before the process's umask).
+   * Does nothing/raises on Windows. */
   mode?: number;
 }
 
-/** Creates a new directory with the specified path synchronously.
- * If `recursive` is set to true, nested directories will be created (also known
- * as "mkdir -p").
- * `mode` sets permission bits (before umask) on UNIX and does nothing on
- * Windows.
+/** Synchronously creates a new directory with the specified path.
  *
  *       Deno.mkdirSync("new_dir");
  *       Deno.mkdirSync("nested/directories", { recursive: true });
- */
+ *
+ * Requires `allow-write` permission. */
 export function mkdirSync(
   path: string,
   optionsOrRecursive?: MkdirOption | boolean,
@@ -48,14 +53,11 @@ export function mkdirSync(
 }
 
 /** Creates a new directory with the specified path.
- * If `recursive` is set to true, nested directories will be created (also known
- * as "mkdir -p").
- * `mode` sets permission bits (before umask) on UNIX and does nothing on
- * Windows.
  *
  *       await Deno.mkdir("new_dir");
  *       await Deno.mkdir("nested/directories", { recursive: true });
- */
+ *
+ * Requires `allow-write` permission. */
 export async function mkdir(
   path: string,
   optionsOrRecursive?: MkdirOption | boolean,
diff --git a/cli/js/read_dir.ts b/cli/js/read_dir.ts
index 948bad044..43223e015 100644
--- a/cli/js/read_dir.ts
+++ b/cli/js/read_dir.ts
@@ -15,19 +15,23 @@ function res(response: ReadDirResponse): FileInfo[] {
   );
 }
 
-/** Reads the directory given by path and returns a list of file info
- * synchronously.
+/** Synchronously reads the directory given by `path` and returns an array of
+ * `Deno.FileInfo`.
  *
  *       const files = Deno.readDirSync("/");
- */
+ *
+ * Requires `allow-read` permission. */
 export function readDirSync(path: string): FileInfo[] {
   return res(sendSync("op_read_dir", { path }));
 }
 
-/** Reads the directory given by path and returns a list of file info.
+/** UNSTABLE: Maybe need to return an `AsyncIterable`.
+ *
+ * Reads the directory given by `path` and resolves to an array of `Deno.FileInfo`.
  *
  *       const files = await Deno.readDir("/");
- */
+ *
+ * Requires `allow-read` permission. */
 export async function readDir(path: string): Promise<FileInfo[]> {
   return res(await sendAsync("op_read_dir", { path }));
 }
diff --git a/cli/js/read_file.ts b/cli/js/read_file.ts
index 705720b05..31b0348e6 100644
--- a/cli/js/read_file.ts
+++ b/cli/js/read_file.ts
@@ -2,12 +2,13 @@
 import { open, openSync } from "./files.ts";
 import { readAll, readAllSync } from "./buffer.ts";
 
-/** Read the entire contents of a file synchronously.
+/** Reads and returns the entire contents of a file.
  *
  *       const decoder = new TextDecoder("utf-8");
  *       const data = Deno.readFileSync("hello.txt");
  *       console.log(decoder.decode(data));
- */
+ *
+ * Requires `allow-read` permission. */
 export function readFileSync(filename: string): Uint8Array {
   const file = openSync(filename);
   const contents = readAllSync(file);
@@ -15,12 +16,13 @@ export function readFileSync(filename: string): Uint8Array {
   return contents;
 }
 
-/** Read the entire contents of a file.
+/** Reads and resolves to the entire contents of a file.
  *
  *       const decoder = new TextDecoder("utf-8");
  *       const data = await Deno.readFile("hello.txt");
  *       console.log(decoder.decode(data));
- */
+ *
+ * Requires `allow-read` permission. */
 export async function readFile(filename: string): Promise<Uint8Array> {
   const file = await open(filename);
   const contents = await readAll(file);
diff --git a/cli/js/read_link.ts b/cli/js/read_link.ts
index 5432bedf7..6f43e8867 100644
--- a/cli/js/read_link.ts
+++ b/cli/js/read_link.ts
@@ -1,18 +1,20 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "./dispatch_json.ts";
 
-/** Returns the destination of the named symbolic link synchronously.
+/** Returns the destination of the named symbolic link.
  *
  *       const targetPath = Deno.readlinkSync("symlink/path");
- */
+ *
+ * Requires `allow-read` permission. */
 export function readlinkSync(name: string): string {
   return sendSync("op_read_link", { name });
 }
 
-/** Returns the destination of the named symbolic link.
+/** Resolves to the destination of the named symbolic link.
  *
  *       const targetPath = await Deno.readlink("symlink/path");
- */
+ *
+ * Requires `allow-read` permission. */
 export async function readlink(name: string): Promise<string> {
   return await sendAsync("op_read_link", { name });
 }
diff --git a/cli/js/remove.ts b/cli/js/remove.ts
index 53ceb825b..4d15cf241 100644
--- a/cli/js/remove.ts
+++ b/cli/js/remove.ts
@@ -2,27 +2,29 @@
 import { sendSync, sendAsync } from "./dispatch_json.ts";
 
 export interface RemoveOption {
+  /** Defaults to `false`. If set to `true`, path will be removed even if
+   * it's a non-empty directory. */
   recursive?: boolean;
 }
 
-/** Removes the named file, directory or symlink synchronously. Would throw
- * error if permission denied, not found, or directory not empty if `recursive`
- * set to false.
- * `recursive` is set to false by default.
+/** Synchronously removes the named file or directory. Throws error if
+ * permission denied, path not found, or path is a non-empty directory and
+ * the `recursive` option isn't set to `true`.
  *
- *       Deno.removeSync("/path/to/dir/or/file", {recursive: false});
- */
+ *       Deno.removeSync("/path/to/dir/or/file", { recursive: false });
+ *
+ * Requires `allow-write` permission. */
 export function removeSync(path: string, options: RemoveOption = {}): void {
   sendSync("op_remove", { path, recursive: !!options.recursive });
 }
 
-/** Removes the named file, directory or symlink. Would throw error if
- * permission denied, not found, or directory not empty if `recursive` set
- * to false.
- * `recursive` is set to false by default.
+/** Removes the named file or directory. Throws error if permission denied,
+ * path not found, or path is a non-empty directory and the `recursive`
+ * option isn't set to `true`.
+ *
+ *       await Deno.remove("/path/to/dir/or/file", { recursive: false });
  *
- *       await Deno.remove("/path/to/dir/or/file", {recursive: false});
- */
+ * Requires `allow-write` permission. */
 export async function remove(
   path: string,
   options: RemoveOption = {}
diff --git a/cli/js/rename.ts b/cli/js/rename.ts
index a689061a2..ec5c18b87 100644
--- a/cli/js/rename.ts
+++ b/cli/js/rename.ts
@@ -7,7 +7,8 @@ import { sendSync, sendAsync } from "./dispatch_json.ts";
  * directories.
  *
  *       Deno.renameSync("old/path", "new/path");
- */
+ *
+ * Requires `allow-read` and `allow-write` permissions. */
 export function renameSync(oldpath: string, newpath: string): void {
   sendSync("op_rename", { oldpath, newpath });
 }
@@ -17,7 +18,8 @@ export function renameSync(oldpath: string, newpath: string): void {
  * when `oldpath` and `newpath` are in different directories.
  *
  *       await Deno.rename("old/path", "new/path");
- */
+ *
+ * Requires `allow-read` and `allow-write`. */
 export async function rename(oldpath: string, newpath: string): Promise<void> {
   await sendAsync("op_rename", { oldpath, newpath });
 }
diff --git a/cli/js/stat.ts b/cli/js/stat.ts
index e742451fd..ea4ab1014 100644
--- a/cli/js/stat.ts
+++ b/cli/js/stat.ts
@@ -23,12 +23,13 @@ export interface StatResponse {
   blocks: number;
 }
 
-/** Queries the file system for information on the path provided. If the given
- * path is a symlink information about the symlink will be returned.
+/** Resolves to a `Deno.FileInfo` for the specified path. If path is a
+ * symlink, information for the symlink will be returned.
  *
  *       const fileInfo = await Deno.lstat("hello.txt");
  *       assert(fileInfo.isFile());
- */
+ *
+ * Requires `allow-read` permission. */
 export async function lstat(filename: string): Promise<FileInfo> {
   const res = (await sendAsync("op_stat", {
     filename,
@@ -37,13 +38,13 @@ export async function lstat(filename: string): Promise<FileInfo> {
   return new FileInfoImpl(res);
 }
 
-/** Queries the file system for information on the path provided synchronously.
- * If the given path is a symlink information about the symlink will be
- * returned.
+/** Synchronously returns a `Deno.FileInfo` for the specified path. If
+ * path is a symlink, information for the symlink will be returned.
  *
  *       const fileInfo = Deno.lstatSync("hello.txt");
  *       assert(fileInfo.isFile());
- */
+ *
+ * Requires `allow-read` permission. */
 export function lstatSync(filename: string): FileInfo {
   const res = sendSync("op_stat", {
     filename,
@@ -52,12 +53,13 @@ export function lstatSync(filename: string): FileInfo {
   return new FileInfoImpl(res);
 }
 
-/** Queries the file system for information on the path provided. `stat` Will
- * always follow symlinks.
+/** Resolves to a `Deno.FileInfo` for the specified path. Will always follow
+ * symlinks.
  *
  *       const fileInfo = await Deno.stat("hello.txt");
  *       assert(fileInfo.isFile());
- */
+ *
+ * Requires `allow-read` permission. */
 export async function stat(filename: string): Promise<FileInfo> {
   const res = (await sendAsync("op_stat", {
     filename,
@@ -66,12 +68,13 @@ export async function stat(filename: string): Promise<FileInfo> {
   return new FileInfoImpl(res);
 }
 
-/** Queries the file system for information on the path provided synchronously.
- * `statSync` Will always follow symlinks.
+/** Synchronously returns a `Deno.FileInfo` for the specified path. Will
+ * always follow symlinks.
  *
  *       const fileInfo = Deno.statSync("hello.txt");
  *       assert(fileInfo.isFile());
- */
+ *
+ * Requires `allow-read` permission. */
 export function statSync(filename: string): FileInfo {
   const res = sendSync("op_stat", {
     filename,
diff --git a/cli/js/stat_test.ts b/cli/js/stat_test.ts
index 98ef091ab..147e3842e 100644
--- a/cli/js/stat_test.ts
+++ b/cli/js/stat_test.ts
@@ -52,9 +52,9 @@ testPerm({ read: true }, async function lstatSyncSuccess(): Promise<void> {
   assert(!modulesInfo.isDirectory());
   assert(modulesInfo.isSymlink());
 
-  const i = Deno.lstatSync("core");
-  assert(i.isDirectory());
-  assert(!i.isSymlink());
+  const coreInfo = Deno.lstatSync("core");
+  assert(coreInfo.isDirectory());
+  assert(!coreInfo.isSymlink());
 });
 
 testPerm({ read: false }, async function lstatSyncPerm(): Promise<void> {
@@ -92,9 +92,9 @@ testPerm({ read: true }, async function statSuccess(): Promise<void> {
   assert(modulesInfo.isDirectory());
   assert(!modulesInfo.isSymlink());
 
-  const i = await Deno.stat("cli/tests");
-  assert(i.isDirectory());
-  assert(!i.isSymlink());
+  const testsInfo = await Deno.stat("cli/tests");
+  assert(testsInfo.isDirectory());
+  assert(!testsInfo.isSymlink());
 });
 
 testPerm({ read: false }, async function statPerm(): Promise<void> {
@@ -132,9 +132,9 @@ testPerm({ read: true }, async function lstatSuccess(): Promise<void> {
   assert(!modulesInfo.isDirectory());
   assert(modulesInfo.isSymlink());
 
-  const i = await Deno.lstat("core");
-  assert(i.isDirectory());
-  assert(!i.isSymlink());
+  const coreInfo = await Deno.lstat("core");
+  assert(coreInfo.isDirectory());
+  assert(!coreInfo.isSymlink());
 });
 
 testPerm({ read: false }, async function lstatPerm(): Promise<void> {
diff --git a/cli/js/symlink.ts b/cli/js/symlink.ts
index de4d8a729..e484ce4a3 100644
--- a/cli/js/symlink.ts
+++ b/cli/js/symlink.ts
@@ -3,12 +3,15 @@ import { sendSync, sendAsync } from "./dispatch_json.ts";
 import * as util from "./util.ts";
 import { build } from "./build.ts";
 
-/** Synchronously creates `newname` as a symbolic link to `oldname`. The type
- * argument can be set to `dir` or `file` and is only available on Windows
- * (ignored on other platforms).
+/** **UNSTABLE**: `type` argument type may be changed to `"dir" | "file"`.
+ *
+ * Creates `newname` as a symbolic link to `oldname`. The type argument can be
+ * set to `dir` or `file`. Is only available on Windows and ignored on other
+ * platforms.
  *
  *       Deno.symlinkSync("old/name", "new/name");
- */
+ *
+ * Requires `allow-read` and `allow-write` permissions. */
 export function symlinkSync(
   oldname: string,
   newname: string,
@@ -20,12 +23,15 @@ export function symlinkSync(
   sendSync("op_symlink", { oldname, newname });
 }
 
-/** Creates `newname` as a symbolic link to `oldname`. The type argument can be
- * set to `dir` or `file` and is only available on Windows (ignored on other
- * platforms).
+/** **UNSTABLE**: `type` argument may be changed to "dir" | "file"
+ *
+ * Creates `newname` as a symbolic link to `oldname`. The type argument can be
+ * set to `dir` or `file`. Is only available on Windows and ignored on other
+ * platforms.
  *
  *       await Deno.symlink("old/name", "new/name");
- */
+ *
+ * Requires `allow-read` and `allow-write` permissions. */
 export async function symlink(
   oldname: string,
   newname: string,
diff --git a/cli/js/truncate.ts b/cli/js/truncate.ts
index 17c08674c..d784b3614 100644
--- a/cli/js/truncate.ts
+++ b/cli/js/truncate.ts
@@ -13,21 +13,21 @@ function coerceLen(len?: number): number {
   return len;
 }
 
-/** Truncates or extends the specified file synchronously, updating the size of
- * this file to become size.
+/** Synchronously truncates or extends the specified file, to reach the
+ * specified `len`.
  *
  *       Deno.truncateSync("hello.txt", 10);
- */
+ *
+ * Requires `allow-write` permission. */
 export function truncateSync(name: string, len?: number): void {
   sendSync("op_truncate", { name, len: coerceLen(len) });
 }
 
-/**
- * Truncates or extends the specified file, updating the size of this file to
- * become size.
+/** Truncates or extends the specified file, to reach the specified `len`.
  *
  *       await Deno.truncate("hello.txt", 10);
- */
+ *
+ * Requires `allow-write` permission. */
 export async function truncate(name: string, len?: number): Promise<void> {
   await sendAsync("op_truncate", { name, len: coerceLen(len) });
 }
diff --git a/cli/js/utime.ts b/cli/js/utime.ts
index d80b8b396..102e5f359 100644
--- a/cli/js/utime.ts
+++ b/cli/js/utime.ts
@@ -5,12 +5,15 @@ function toSecondsFromEpoch(v: number | Date): number {
   return v instanceof Date ? v.valueOf() / 1000 : v;
 }
 
-/** Synchronously changes the access and modification times of a file system
+/** **UNSTABLE**: needs investigation into high precision time.
+ *
+ * Synchronously changes the access and modification times of a file system
  * object referenced by `filename`. Given times are either in seconds
  * (Unix epoch time) or as `Date` objects.
  *
  *       Deno.utimeSync("myfile.txt", 1556495550, new Date());
- */
+ *
+ * Requires `allow-write` permission. */
 export function utimeSync(
   filename: string,
   atime: number | Date,
@@ -24,12 +27,15 @@ export function utimeSync(
   });
 }
 
-/** Changes the access and modification times of a file system object
+/** **UNSTABLE**: needs investigation into high precision time.
+ *
+ * Changes the access and modification times of a file system object
  * referenced by `filename`. Given times are either in seconds
  * (Unix epoch time) or as `Date` objects.
  *
  *       await Deno.utime("myfile.txt", 1556495550, new Date());
- */
+ *
+ * Requires `allow-write` permission. */
 export async function utime(
   filename: string,
   atime: number | Date,
diff --git a/cli/js/write_file.ts b/cli/js/write_file.ts
index 089b235ed..445e4550d 100644
--- a/cli/js/write_file.ts
+++ b/cli/js/write_file.ts
@@ -4,22 +4,26 @@ import { open, openSync } from "./files.ts";
 import { chmod, chmodSync } from "./chmod.ts";
 import { writeAll, writeAllSync } from "./buffer.ts";
 
-/** Options for writing to a file.
- * `perm` would change the file's permission if set.
- * `create` decides if the file should be created if not exists (default: true)
- * `append` decides if the file should be appended (default: false)
- */
+/** Options for writing to a file. */
 export interface WriteFileOptions {
-  perm?: number;
-  create?: boolean;
+  /** Defaults to `false`. If set to `true`, will append to a file instead of
+   * overwriting previous contents. */
   append?: boolean;
+  /** Sets the option to allow creating a new file, if one doesn't already
+   * exist at the specified path (defaults to `true`). */
+  create?: boolean;
+  /** Permissions always applied to file. */
+  perm?: number;
 }
 
-/** Write a new file, with given filename and data synchronously.
+/** Synchronously write data to the given path, by default creating a new
+ * file if needed, else overwriting.
  *
  *       const encoder = new TextEncoder();
  *       const data = encoder.encode("Hello world\n");
  *       Deno.writeFileSync("hello.txt", data);
+ *
+ * Requires `allow-write` permission, and `allow-read` if create is `false`.
  */
 export function writeFileSync(
   filename: string,
@@ -45,11 +49,14 @@ export function writeFileSync(
   file.close();
 }
 
-/** Write a new file, with given filename and data.
+/** Write data to the given path, by default creating a new file if needed,
+ * else overwriting.
  *
  *       const encoder = new TextEncoder();
  *       const data = encoder.encode("Hello world\n");
  *       await Deno.writeFile("hello.txt", data);
+ *
+ * Requires `allow-write` permission, and `allow-read` if create is `false`.
  */
 export async function writeFile(
   filename: string,
diff --git a/cli/ops/fs.rs b/cli/ops/fs.rs
index 4d7bd9d15..adf090182 100644
--- a/cli/ops/fs.rs
+++ b/cli/ops/fs.rs
@@ -13,9 +13,7 @@ use std::path::Path;
 use std::time::UNIX_EPOCH;
 
 #[cfg(unix)]
-use std::os::unix::fs::MetadataExt;
-#[cfg(unix)]
-use std::os::unix::fs::PermissionsExt;
+use std::os::unix::fs::{MetadataExt, PermissionsExt};
 
 pub fn init(i: &mut Isolate, s: &State) {
   i.register_op("op_chdir", s.stateful_json_op(op_chdir));
@@ -104,7 +102,7 @@ fn op_chmod(
     debug!("op_chmod {}", path.display());
     // Still check file/dir exists on windows
     let _metadata = fs::metadata(&path)?;
-    #[cfg(any(unix))]
+    #[cfg(unix)]
     {
       let mut permissions = _metadata.permissions();
       permissions.set_mode(args.mode);
@@ -136,10 +134,8 @@ fn op_chown(
   let is_sync = args.promise_id.is_none();
   blocking_json(is_sync, move || {
     debug!("op_chown {}", path.display());
-    match deno_fs::chown(args.path.as_ref(), args.uid, args.gid) {
-      Ok(_) => Ok(json!({})),
-      Err(e) => Err(OpError::from(e)),
-    }
+    deno_fs::chown(args.path.as_ref(), args.uid, args.gid)?;
+    Ok(json!({}))
   })
 }
 
@@ -201,13 +197,14 @@ fn op_copy_file(
   debug!("op_copy_file {} {}", from.display(), to.display());
   let is_sync = args.promise_id.is_none();
   blocking_json(is_sync, move || {
-    // On *nix, Rust deem non-existent path as invalid input
+    // On *nix, Rust reports non-existent `from` as ErrorKind::InvalidInput
     // See https://github.com/rust-lang/rust/issues/54800
-    // Once the issue is reolved, we should remove this workaround.
+    // Once the issue is resolved, we should remove this workaround.
     if cfg!(unix) && !from.is_file() {
       return Err(OpError::not_found("File not found".to_string()));
     }
 
+    // returns length of from as u64 (we ignore)
     fs::copy(&from, &to)?;
     Ok(json!({}))
   })
@@ -451,13 +448,13 @@ fn op_symlink(
 
   state.check_write(&newname)?;
   // TODO Use type for Windows.
-  if cfg!(windows) {
+  if cfg!(not(unix)) {
     return Err(OpError::other("Not implemented".to_string()));
   }
   let is_sync = args.promise_id.is_none();
   blocking_json(is_sync, move || {
     debug!("op_symlink {} {}", oldname.display(), newname.display());
-    #[cfg(any(unix))]
+    #[cfg(unix)]
     std::os::unix::fs::symlink(&oldname, &newname)?;
     Ok(json!({}))
   })
@@ -597,7 +594,7 @@ fn op_make_temp_file(
 
 #[derive(Deserialize)]
 #[serde(rename_all = "camelCase")]
-struct Utime {
+struct UtimeArgs {
   promise_id: Option<u64>,
   filename: String,
   atime: u64,
@@ -609,11 +606,11 @@ fn op_utime(
   args: Value,
   _zero_copy: Option<ZeroCopyBuf>,
 ) -> Result<JsonOp, OpError> {
-  let args: Utime = serde_json::from_value(args)?;
+  let args: UtimeArgs = serde_json::from_value(args)?;
   state.check_write(Path::new(&args.filename))?;
   let is_sync = args.promise_id.is_none();
   blocking_json(is_sync, move || {
-    debug!("op_utimes {} {} {}", args.filename, args.atime, args.mtime);
+    debug!("op_utime {} {} {}", args.filename, args.atime, args.mtime);
     utime::set_file_times(args.filename, args.atime, args.mtime)?;
     Ok(json!({}))
   })