Cleanup comments and internal variables (#4205)

cli/fs.rs

@@ -10,12 +10,11 @@ use rand;
 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))
 }

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 changes the permission of a specific file/directory of
- * synchronously.
+ * 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 });
 }

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";
 
-/**
+/** Synchronously change owner of a regular file or directory. Linux/Mac OS
- * Change owner of a regular file or directory synchronously. Unix only at the moment.
+ * 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. Linux/Mac OS only at the
- * Change owner of a regular file or directory asynchronously. Unix only at the moment.
+ * 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

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.
+/** Synchronously copies the contents and permissions of one file to another
- * Creates a new file if target does not exists, and if target exists,
+ * specified path, by default creating a new file if needed, else overwriting.
- * overwrites original content of the target file.
+ * Fails if target path is a directory or is unwritable.
- *
- * It would also copy the permission of the original file
- * to the destination.
  *
  *       Deno.copyFileSync("from.txt", "to.txt");
- */
+ *
-export function copyFileSync(from: string, to: string): void {
+ * Requires `allow-read` permission on fromPath.
-  sendSync("op_copy_file", { from, to });
+ * 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.
+/** 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
- * Creates a new file if target does not exists, and if target exists,
+ * path is a directory or is unwritable.
- * overwrites original content of the target file.
- *
- * It would also copy the permission of the original file
- * to the destination.
  *
  *       await Deno.copyFile("from.txt", "to.txt");
- */
+ *
-export async function copyFile(from: string, to: string): Promise<void> {
+ * Requires `allow-read` permission on fromPath.
-  await sendAsync("op_copy_file", { from, to });
+ * 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 });
 }

cli/js/dir.ts

@@ -2,19 +2,25 @@
 import { sendSync } from "./dispatch_json.ts";
 
 /**
- * `cwd()` Return a string representing the current working directory.
+ * **UNSTABLE**: maybe needs permissions.
- * If the current directory can be reached via multiple paths
+ *
- * (due to symbolic links), `cwd()` may return
+ * Return a string representing the current working directory.
- * any one of them.
+ *
- * throws `NotFound` exception if directory not available
+ * 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.
+ * **UNSTABLE**: maybe needs permissions.
- * throws `NotFound` exception if directory not available
+ *
+ * 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 });

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
+   * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This
-   * be available on all platforms.
+   * 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
+   * field from `stat` on Mac/BSD and `ftCreationTime` on Windows. This may not
-   * be available on all platforms.
+   * be available on all platforms. */
-   */
   created: number | null;
-
   /** The file or directory name. */
   name: string | null;
-
+  /** ID of the device containing the file.
-  /** ID of the device containing the file. Unix only. */
+   *
+   * _Linux/Mac OS only._ */
   dev: number | null;
-
+  /** Inode number.
-  /** Inode number. Unix only. */
+   *
+   * _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.
-  /** Number of hard links pointing to this file. Unix only. */
+   *
+   * _Linux/Mac OS only._ */
   nlink: number | null;
-
+  /** User ID of the owner of this file.
-  /** User ID of the owner of this file. Unix only. */
+   *
+   * _Linux/Mac OS only._ */
   uid: number | null;
-
+  /** User ID of the owner of this file.
-  /** User ID of the owner of this file. Unix only. */
+   *
+   * _Linux/Mac OS only._ */
   gid: number | null;
-
+  /** Device ID of this file.
-  /** Device ID of this file. Unix only. */
+   *
+   * _Linux/Mac OS only._ */
   rdev: number | null;
-
+  /** Blocksize for filesystem I/O.
-  /** Blocksize for filesystem I/O. Unix only. */
+   *
+   * _Linux/Mac OS only._ */
   blksize: number | null;
-
+  /** Number of blocks allocated to the file, in 512-byte units.
-  /** Number of blocks allocated to the file, in 512-byte units. Unix only. */
+   *
+   * _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;
 }
 

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 open a file and return an instance of the `File` object.
- *  synchronously.
  *
  *       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;
+export function openSync(filename: string, mode?: 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");
+ *
+ * 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
+/** Creates a file if none exists or truncates an existing file and resolves to
- *  an instance of the `File` object.
+ *  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.
+  /** Sets the option for write access. This option, when `true`, means that
-   * This option, when true, will indicate that the file should be write-able if opened.
+   * the file should be write-able if opened. If the file already exists,
-   * If the file already exists, any write calls on it will overwrite its contents, without truncating it.
+   * any write calls on it will overwrite its contents, by default without
-   */
+   * truncating it. */
   write?: boolean;
-  /** Sets the option for creating a new file.
+  /**Sets the option for the append mode. This option, when `true`, means that
-   * This option indicates whether a new file will be created if the file does not yet already exist.
+   * writes will append to a file instead of overwriting previous contents.
-   * In order for the file to be created, write or append access must be used.
+   * Note that setting `{ write: true, append: true }` has the same effect as
-   */
+   * setting only `{ append: true }`. */
-  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 }.
-   */
   append?: boolean;
-  /** Sets the option to always create a new file.
+  /** Sets the option for truncating a previous file. If a file is
-   * This option indicates whether a new file will be created. No file is allowed to exist at the target location, also no (dangling) symlink.
+   * successfully opened with this option set it will truncate the file to `0`
-   * If { createNew: true } is set, create and truncate are ignored.
+   * 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 =
+/** A set of string literals which specify the open mode of a file.
-  /** Read-only. Default. Starts at beginning of file. */
+ *
-  | "r"
+ * |Value |Description                                                                                       |
-  /** Read-write. Start at beginning of file. */
+ * |------|--------------------------------------------------------------------------------------------------|
-  | "r+"
+ * |`"r"` |Read-only. Default. Starts at beginning of file.                                                  |
-  /** Write-only. Opens and truncates existing file or creates new one for
+ * |`"r+"`|Read-write. Start at beginning of file.                                                           |
-   * writing only.
+ * |`"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.                                        |
  */
-  | "w"
+export type OpenMode = "r" | "r+" | "w" | "w+" | "a" | "a+" | "x" | "x+";
-  /** 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+";
 
 /** Check if OpenOptions is set to valid combination of options.
  *  @returns Tuple representing if openMode is valid and error message if it's not

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
+  /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number of
-   * of bytes read (`0` <= `n` <= `p.byteLength`) and rejects if any error encountered.
+   * bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error
-   * Even if `read()` returns `n` < `p.byteLength`, it may use all of `p` as
+   * encountered. Even if `read()` resolves to `n` < `p.byteLength`, it may
-   * scratch space during the call. If some data is available but not
+   * use all of `p` as scratch space during the call. If some data is
-   * `p.byteLength` bytes, `read()` conventionally returns what is available
+   * available but not `p.byteLength` bytes, `read()` conventionally resolves
-   * instead of waiting for more.
+   * 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 resolves to
-   *
+   * `Deno.EOF` symbol.
-   * When `read()` encounters end-of-file condition, it returns 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
+  /** Writes `p.byteLength` bytes from `p` to the underlying data stream. It
-   * stream. It resolves to the number of bytes written from `p` (`0` <= `n` <=
+   * resolves to the number of bytes written from `p` (`0` <= `n` <=
-   * `p.byteLength`) and any error encountered that caused the write to stop
+   * `p.byteLength`) or reject with the error encountered that caused the
-   * early. `write()` must return a non-null error if it returns `n` <
+   * write to stop early. `write()` must reject with a non-null error if
-   * `p.byteLength`. write() must not modify the slice data, even temporarily.
+   * 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
+   * interpreted according to `whence`: `SEEK_START` means relative to the
-   * of the file, `SeekCurrent` means relative to the current offset, and
+   * start of the file, `SEEK_CURRENT` means relative to the current offset,
-   * `SeekEnd` means relative to the end. Seek returns the new offset relative
+   * and `SEEK_END` means relative to the end.
-   * 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
+   * any positive offset is legal, but the behavior of subsequent I/O
-   * on the underlying object is implementation-dependent.
+   * 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`
+/** Copies from `src` to `dst` until either `EOF` is reached on `src` or an
- * or an error occurs. It returns the number of bytes copied and the first
+ * error occurs. It resolves to the number of bytes copied or rejects with
- * error encountered while copying, if any.
+ * 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> {

cli/js/lib.deno.ns.d.ts

@@ -50,19 +50,19 @@ declare namespace Deno {
    * 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
+    /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number of
-     * of bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error
+     * bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error
-     * encountered. Even if `read()` returns `n` < `p.byteLength`, it may use
+     * encountered. Even if `read()` resolves to `n` < `p.byteLength`, it may
-     * all of `p` as scratch space during the call. If some data is available
+     * use all of `p` as scratch space during the call. If some data is
-     * but not `p.byteLength` bytes, `read()` conventionally returns what is
+     * available but not `p.byteLength` bytes, `read()` conventionally resolves
-     * available instead of waiting for more.
+     * to what is available instead of waiting for more.
      *
-     * When `read()` encounters end-of-file condition, it returns `Deno.EOF`
+     * When `read()` encounters end-of-file condition, it resolves to
-     * symbol.
+     * `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
+    /** Writes `p.byteLength` bytes from `p` to the underlying data stream. It
-     * stream. It resolves with the number of bytes written from `p` (`0` <= `n`
+     * resolves to the number of bytes written from `p` (`0` <= `n` <=
-     * <= `p.byteLength`) or reject with the error encountered that caused the
+     * `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
+     * write to stop early. `write()` must reject with a non-null error if
-     * returns `n` < `p.byteLength`. `write()` must not modify the slice data,
+     * would resolve to `n` < `p.byteLength`. `write()` must not modify the
-     * even temporarily.
+     * 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
+     * interpreted according to `whence`: `SEEK_START` means relative to the
-     * start of the file, `SeekCurrent` means relative to the current offset,
+     * start of the file, `SEEK_CURRENT` means relative to the current offset,
-     * and `SeekEnd` means relative to the end. Seek returns the new offset
+     * and `SEEK_END` means relative to the end. Seek resolves to the new offset
-     * relative to the start of the file and an error, if any.
+     * 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
+     * offset, interpreted according to `whence`: `SEEK_START` means relative
-     * the start of the file, `SeekCurrent` means relative to the current
+     * to the start of the file, `SEEK_CURRENT` means relative to the current
-     * offset, and `SeekEnd` means relative to the end. Seek returns the new
+     * offset, and `SEEK_END` means relative to the end.
-     * 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
@@ -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
+   * error occurs. It resolves to the number of bytes copied or rejects with
-   * encountered while copying, if any.
+   * 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);
-   *      })();
    */
   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.
+    /** Sets the option for read access. This option, when `true`, means that the
-     *
+     * file should be read-able if opened. */
-     * This option, when `true`, will indicate that the file should be readable
-     * if opened. */
     read?: boolean;
-    /** Sets the option for write access.
+    /** 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,
-     * This option, when `true`, will indicate that the file should be
+     * any write calls on it will overwrite its contents, by default without
-     * writeable if opened.
+     * truncating it. */
-     *
-     * If the file already exists, any write calls on it will overwrite
-     * its contents, without truncating it. */
     write?: boolean;
-    /** Sets the option for creating a new file.
+    /**Sets the option for the append mode. This option, when `true`, means that
-     *
+     * writes will append to a file instead of overwriting previous contents.
-     * 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 }`. */
     append?: boolean;
-    /** Sets the option to always create a new file.
+    /** 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`
-     * This option indicates whether a new file will be created. No file is
+     * length if it already exists. The file must be opened with write access
-     * allowed to exist at the target location, also no (dangling) symlink.
+     * for truncate to work. */
-     *
+    truncate?: boolean;
-     * If `{ createNew: true }` is set, `create` and `truncate` value are
+    /** Sets the option to allow creating a new file, if one doesn't already
-     * ignored. */
+     * 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;
   }
 
@@ -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
+     * drained. Resolves to the number of bytes read. If the buffer has no
-     * data to return, resolves with `Deno.EOF`. */
+     * 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
+    /** Defaults to `false`. If set to `true`, means that any intermediate
-     * `mkdir -p`) */
+     * 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
+    /** Permissions to use when creating the directory (defaults to `0o777`,
-     * on Windows */
+     * before the process's umask).
+     * Does nothing/raises on Windows. */
     mode?: number;
   }
 
-  /** Creates a new directory with the specified path synchronously.
+  /** Synchronously 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.
    *
    *       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 */
@@ -766,18 +745,11 @@ declare namespace Deno {
   ): void;
 
   /** 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
+  /** Synchronously creates a new temporary directory in the directory `dir`,
-   * beginning with `prefix` and ending with `suffix`.
+   * 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.
+   * If `dir` is unspecified, uses the default directory for temporary files.
-   * Multiple programs calling simultaneously will not choose the same
+   * Multiple programs calling this function simultaneously will create different
-   * directory. It is the caller's responsibility to remove the directory
+   * directories. It is the caller's responsibility to remove the directory when
-   * when no longer needed.
+   * 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.
+   * If `dir` is unspecified, uses the default directory for temporary files.
-   * Multiple programs calling simultaneously will not choose the same
+   * Multiple programs calling this function simultaneously will create different
-   * directory. It is the caller's responsibility to remove the directory
+   * directories. It is the caller's responsibility to remove the directory when
-   * when no longer needed.
+   * 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
+  /** Synchronously creates a new temporary file in the directory `dir`, its name
-   * with `prefix` and ending with `suffix`.
+   * 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.
+   * If `dir` is unspecified, uses the default directory for temporary files.
-   * Multiple programs calling simultaneously will not choose the same
+   * Multiple programs calling this function simultaneously will create different
-   * directory. It is the caller's responsibility to remove the file when no
+   * files. It is the caller's responsibility to remove the file when
-   * longer needed.
+   * 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
+  /** Creates a new temporary file in the directory `dir`, its name
-   * with `prefix` and ending with `suffix`.
+   * 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.
+   * If `dir` is unspecified, uses the default directory for temporary files.
-   * Multiple programs calling simultaneously will not choose the same
+   * Multiple programs calling this function simultaneously will create different
-   * directory. It is the caller's responsibility to remove the file when no
+   * files. It is the caller's responsibility to remove the file when
-   * longer needed.
+   * 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
+  // @url js/chmod.d.ts
-   * synchronously.
+
+  /** 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
+  /** Change owner of a regular file or directory. Linux/Mac OS only at the
-   * only at the moment.
+   * 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
+  /** Synchronously removes the named file or directory. Throws error if
-   * permission denied, not found, or directory not empty if `recursive` set to
+   * permission denied, path not found, or path is a non-empty directory and
-   * `false`.
+   * the `recursive` option isn't set to `true`.
-   *
-   * `recursive` defaults to `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
+  /** Removes the named file or directory. Throws error if permission denied,
-   * permission denied, not found, or directory not empty if `recursive` set
+   * path not found, or path is a non-empty directory and the `recursive`
-   * to false.
+   * option isn't set to `true`.
-   *
-   * `recursive` defaults to `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`,
+   * A FileInfo describes a file and is returned by `stat`, `lstat`,
-   * `lstatSync`.
+   * `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
+    /** The last access time of the file. This corresponds to the `atime`
-     * from `stat` on Linux/Mac OS and `ftLastAccessTime` on Windows. This may
+     * field from `stat` on Unix and `ftLastAccessTime` on Windows. This may not
-     * 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 Linux/Mac OS and `ftCreationTime` on Windows. This
+     * field from `stat` on Mac/BSD and `ftCreationTime` on Windows. This may not
-     * may not be available on all platforms. */
+     * 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
+   * Reads the directory given by `path` and resolves to an array of `Deno.FileInfo`.
-   * `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.
+  // @url js/copy_file.d.ts
-   *
+
-   * Creates a new file if target does not exists, and if target exists,
+  /** Synchronously copies the contents and permissions of one file to another
-   * overwrites original content of the target file.
+   * specified path, by default creating a new file if needed, else overwriting.
-   *
+   * Fails if target path is a directory or is unwritable.
-   * It will also copy the permissions of the original file to the destination.
    *
    *       Deno.copyFileSync("from.txt", "to.txt");
    *
-   * Requires `allow-read` and `allow-write` permissions. */
+   * Requires `allow-read` permission on fromPath.
-  export function copyFileSync(from: string, to: string): void;
+   * Requires `allow-write` permission on toPath. */
+  export function copyFileSync(fromPath: string, toPath: string): void;
 
-  /** Copies the contents of a file to another by name.
+  /** 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
-   * Creates a new file if target does not exists, and if target exists,
+   * path is a directory or is unwritable.
-   * overwrites original content of the target file.
-   *
-   * It will also copy the permissions of the original file to the destination.
    *
    *       await Deno.copyFile("from.txt", "to.txt");
    *
-   * Requires `allow-read` and `allow-write` permissions. */
+   * Requires `allow-read` permission on fromPath.
-  export function copyFile(from: string, to: string): Promise<void>;
+   * 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
+  // @url js/stat.d.ts
-   * `filename` 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());
@@ -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
+  /** Synchronously returns a `Deno.FileInfo` for the specified path. If
-   * `filename` is a symlink, information about the symlink will be returned.
+   * 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
+  /** Resolves to a `Deno.FileInfo` for the specified path. Will always follow
-   * resolve and follow symlinks.
+   * 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
+  /** Synchronously returns a `Deno.FileInfo` for the specified path. Will
-   * and follow symlinks.
+   * 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. */
+    /** Defaults to `false`. If set to `true`, will append to a file instead of
-    perm?: number;
+     * overwriting previous contents. */
-    /** Create the file if it does not exist.  Defaults to `true`. */
-    create?: boolean;
-    /** Append to the file.  Defaults to `false`. */
     append?: boolean;
+    /** Sets the option to allow creating a new file, if one doesn't already
+     * exist at the specified path (defaults to `true`). */
+    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,
@@ -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`.
      *
@@ -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

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
+     * interpreted according to `whence`: `SEEK_START` means relative to the
-     * of the file, `SeekCurrent` means relative to the current offset, and
+     * start of the file, `SEEK_CURRENT` means relative to the current offset,
-     * `SeekEnd` means relative to the end. Seek returns the new offset relative
+     * and `SEEK_END` means relative to the end. Seek returns the new offset
-     * to the start of the file and an error, if any.
+     * 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
+     * any positive offset is legal, but the behavior of subsequent I/O
-     * on the underlying object is implementation-dependent.
+     * operations on the underlying object is implementation-dependent.
      */
     seek(offset: number, whence: SeekMode): Promise<void>;
   }

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 });
 }

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
+/** Creates a new temporary directory in the directory `dir`, its name
- * name beginning with `prefix` and ending with `suffix`.
+ * 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
+ * It resolves to the full path to the newly created directory.
- * files. Multiple programs calling tempDir simultaneously will not choose the
+ *
- * same directory. It is the caller's responsibility to remove the directory
+ * If `dir` is unspecified, uses the default directory for temporary files.
- * when no longer needed.
+ * 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
+/** Creates a new temporary file in the directory `dir`, its name
- * name beginning with `prefix` and ending with `suffix`.
+ * 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
+ * It resolves to the full path to the newly created file.
- * files. Multiple programs calling tempFile simultaneously will not choose the
+ *
- * same directory. It is the caller's responsibility to remove the file
+ * If `dir` is unspecified, uses the default directory for temporary files.
- * when no longer needed.
+ * 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> {

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.
+/** Synchronously 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.
  *
  *       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,

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 reads the directory given by `path` and returns an array of
- * synchronously.
+ * `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 }));
 }

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);

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 });
 }

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
+/** Synchronously removes the named file or directory. Throws error if
- * error if permission denied, not found, or directory not empty if `recursive`
+ * permission denied, path not found, or path is a non-empty directory and
- * set to false.
+ * the `recursive` option isn't set to `true`.
- * `recursive` is set to false by default.
  *
  *       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
+/** Removes the named file or directory. Throws error if permission denied,
- * permission denied, not found, or directory not empty if `recursive` set
+ * path not found, or path is a non-empty directory and the `recursive`
- * to false.
+ * option isn't set to `true`.
- * `recursive` is set to false by default.
  *
  *       await Deno.remove("/path/to/dir/or/file", { recursive: false });
- */
+ *
+ * Requires `allow-write` permission. */
 export async function remove(
   path: string,
   options: RemoveOption = {}

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 });
 }

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
+/** Resolves to a `Deno.FileInfo` for the specified path. If path is a
- * path is a symlink information about the symlink will be returned.
+ * 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.
+/** Synchronously returns a `Deno.FileInfo` for the specified path. If
- * If the given path is a symlink information about the symlink will be
+ * path is a symlink, information for the symlink will be returned.
- * 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
+/** Resolves to a `Deno.FileInfo` for the specified path. Will always follow
- * always follow symlinks.
+ * 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.
+/** Synchronously returns a `Deno.FileInfo` for the specified path. Will
- * `statSync` Will always follow symlinks.
+ * 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,

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");
+  const coreInfo = Deno.lstatSync("core");
-  assert(i.isDirectory());
+  assert(coreInfo.isDirectory());
-  assert(!i.isSymlink());
+  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");
+  const testsInfo = await Deno.stat("cli/tests");
-  assert(i.isDirectory());
+  assert(testsInfo.isDirectory());
-  assert(!i.isSymlink());
+  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");
+  const coreInfo = await Deno.lstat("core");
-  assert(i.isDirectory());
+  assert(coreInfo.isDirectory());
-  assert(!i.isSymlink());
+  assert(!coreInfo.isSymlink());
 });
 
 testPerm({ read: false }, async function lstatPerm(): Promise<void> {

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
+/** **UNSTABLE**: `type` argument type may be changed to `"dir" | "file"`.
- * argument can be set to `dir` or `file` and is only available on Windows
+ *
- * (ignored on other platforms).
+ * 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
+/** **UNSTABLE**: `type` argument may be changed to "dir" | "file"
- * set to `dir` or `file` and is only available on Windows (ignored on other
+ *
- * platforms).
+ * 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,

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
+/** Synchronously truncates or extends the specified file, to reach the
- * this file to become size.
+ * 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, to reach the specified `len`.
- * Truncates or extends the specified file, updating the size of this file to
- * become size.
  *
  *       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) });
 }

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,

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.
+/** 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)
- */
 export interface WriteFileOptions {
-  perm?: number;
+  /** Defaults to `false`. If set to `true`, will append to a file instead of
-  create?: boolean;
+   * 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,

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;
+use std::os::unix::fs::{MetadataExt, PermissionsExt};
-#[cfg(unix)]
-use std::os::unix::fs::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) {
+    deno_fs::chown(args.path.as_ref(), args.uid, args.gid)?;
-      Ok(_) => Ok(json!({})),
+    Ok(json!({}))
-      Err(e) => Err(OpError::from(e)),
-    }
   })
 }
 
@@ -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!({}))
   })