Align JSDoc to style guide.

js/blob.ts

@@ -9,6 +9,7 @@ export class DenoBlob implements domTypes.Blob {
   readonly size: number = 0;
   readonly type: string = "";
 
+  /** A blob object represents a file-like object of immutable, raw data. */
   constructor(
     blobParts?: domTypes.BlobPart[],
     options?: domTypes.BlobPropertyBag

js/compiler.ts

@@ -27,38 +27,29 @@ type AMDRequire = (
   errback: AmdErrback
 ) => void;
 
-/**
+/** The location that a module is being loaded from. This could be a directory,
- * The location that a module is being loaded from. This could be a directory,
  * like `.`, or it could be a module specifier like
  * `http://gist.github.com/somefile.ts`
  */
 type ContainingFile = string;
-/**
+/** The internal local filename of a compiled module. It will often be something
- * The internal local filename of a compiled module. It will often be something
  * like `/home/ry/.deno/gen/f7b4605dfbc4d3bb356e98fda6ceb1481e4a8df5.js`
  */
 type ModuleFileName = string;
-/**
+/** The original resolved resource name.
- * The original resolved resource name.
  * Path to cached module file or URL from which dependency was retrieved
  */
 type ModuleId = string;
-/**
+/** The external name of a module - could be a URL or could be a relative path.
- * The external name of a module - could be a URL or could be a relative path.
  * Examples `http://gist.github.com/somefile.ts` or `./somefile.ts`
  */
 type ModuleSpecifier = string;
-/**
+/** The compiled source code which is cached in `.deno/gen/` */
- * The compiled source code which is cached in `.deno/gen/`
- */
 type OutputCode = string;
-/**
+/** The original source code */
- * The original source code
- */
 type SourceCode = string;
 
-/**
+/** Abstraction of the APIs required from the `os` module so they can be
- * Abstraction of the APIs required from the `os` module so they can be
  * easily mocked.
  * @internal
  */
@@ -68,8 +59,7 @@ export interface Os {
   exit: typeof os.exit;
 }
 
-/**
+/** Abstraction of the APIs required from the `typescript` module so they can
- * Abstraction of the APIs required from the `typescript` module so they can
  * be easily mocked.
  * @internal
  */
@@ -79,8 +69,7 @@ export interface Ts {
   formatDiagnosticsWithColorAndContext: typeof ts.formatDiagnosticsWithColorAndContext;
 }
 
-/**
+/** A simple object structure for caching resolved modules and their contents.
- * A simple object structure for caching resolved modules and their contents.
  *
  * Named `ModuleMetaData` to clarify it is just a representation of meta data of
  * the module, not the actual module instance.
@@ -118,8 +107,7 @@ export class ModuleMetaData implements ts.IScriptSnapshot {
   }
 }
 
-/**
+/** A singleton class that combines the TypeScript Language Service host API
- * A singleton class that combines the TypeScript Language Service host API
  * with Deno specific APIs to provide an interface for compiling and running
  * TypeScript and JavaScript modules.
  */
@@ -173,8 +161,7 @@ export class DenoCompiler
   // Flags forcing recompilation of TS code
   public recompile = false;
 
-  /**
+  /** Drain the run queue, retrieving the arguments for the module
-   * Drain the run queue, retrieving the arguments for the module
    * factory and calling the module's factory.
    */
   private _drainRunQueue(): void {
@@ -195,8 +182,7 @@ export class DenoCompiler
     }
   }
 
-  /**
+  /** Get the dependencies for a given module, but don't run the module,
-   * Get the dependencies for a given module, but don't run the module,
    * just add the module factory to the run queue.
    */
   private _gatherDependencies(moduleMetaData: ModuleMetaData): void {
@@ -216,9 +202,7 @@ export class DenoCompiler
     this._window.define = undefined;
   }
 
-  /**
+  /** Retrieve the arguments to pass a module's factory function. */
-   * Retrieve the arguments to pass a module's factory function.
-   */
   // tslint:disable-next-line:no-any
   private _getFactoryArguments(moduleMetaData: ModuleMetaData): any[] {
     if (!moduleMetaData.deps) {
@@ -241,8 +225,7 @@ export class DenoCompiler
     });
   }
 
-  /**
+  /** The TypeScript language service often refers to the resolved fileName of
-   * The TypeScript language service often refers to the resolved fileName of
    * a module, this is a shortcut to avoid unnecessary module resolution logic
    * for modules that may have been initially resolved by a `moduleSpecifier`
    * and `containingFile`.  Also, `resolveModule()` throws when the module
@@ -260,9 +243,7 @@ export class DenoCompiler
         : undefined;
   }
 
-  /**
+  /** Create a localized AMD `define` function and return it. */
-   * Create a localized AMD `define` function and return it.
-   */
   private _makeDefine(moduleMetaData: ModuleMetaData): AmdDefine {
     return (deps: ModuleSpecifier[], factory: AmdFactory): void => {
       this._log("compiler.localDefine", moduleMetaData.fileName);
@@ -295,8 +276,7 @@ export class DenoCompiler
     };
   }
 
-  /**
+  /** Returns a require that specifically handles the resolution of a transpiled
-   * Returns a require that specifically handles the resolution of a transpiled
    * emit of a dynamic ES `import()` from TypeScript.
    */
   private _makeLocalRequire(moduleMetaData: ModuleMetaData): AMDRequire {
@@ -323,8 +303,7 @@ export class DenoCompiler
     };
   }
 
-  /**
+  /** Given a `moduleSpecifier` and `containingFile` retrieve the cached
-   * Given a `moduleSpecifier` and `containingFile` retrieve the cached
    * `fileName` for a given module.  If the module has yet to be resolved
    * this will return `undefined`.
    */
@@ -340,8 +319,8 @@ export class DenoCompiler
     return undefined;
   }
 
-  /**
+  /** Resolve the `fileName` for a given `moduleSpecifier` and
-   * Resolve the `fileName` for a given `moduleSpecifier` and `containingFile`
+   * `containingFile`
    */
   private _resolveModuleName(
     moduleSpecifier: ModuleSpecifier,
@@ -351,8 +330,7 @@ export class DenoCompiler
     return moduleMetaData ? moduleMetaData.fileName : undefined;
   }
 
-  /**
+  /** Caches the resolved `fileName` in relationship to the `moduleSpecifier`
-   * Caches the resolved `fileName` in relationship to the `moduleSpecifier`
    * and `containingFile` in order to reduce calls to the privileged side
    * to retrieve the contents of a module.
    */
@@ -370,8 +348,7 @@ export class DenoCompiler
     innerMap.set(moduleSpecifier, fileName);
   }
 
-  /**
+  /** Setup being able to map back source references back to their source
-   * Setup being able to map back source references back to their source
    *
    * TODO is this the best place for this?  It is tightly coupled to how the
    * compiler works, but it is also tightly coupled to how the whole runtime
@@ -413,8 +390,7 @@ export class DenoCompiler
 
   // Deno specific compiler API
 
-  /**
+  /** Retrieve the output of the TypeScript compiler for a given module and
-   * Retrieve the output of the TypeScript compiler for a given module and
    * cache the result. Re-compilation can be forced using '--recompile' flag.
    */
   compile(moduleMetaData: ModuleMetaData): OutputCode {
@@ -462,9 +438,9 @@ export class DenoCompiler
     return moduleMetaData.outputCode;
   }
 
-  /**
+  /** For a given module specifier and containing file, return a list of
-   * For a given module specifier and containing file, return a list of absolute
+   * absolute identifiers for dependent modules that are required by this
-   * identifiers for dependent modules that are required by this module.
+   * module.
    */
   getModuleDependencies(
     moduleSpecifier: ModuleSpecifier,
@@ -490,8 +466,7 @@ export class DenoCompiler
     return dependencies;
   }
 
-  /**
+  /** Given a `moduleSpecifier` and `containingFile`, resolve the module and
-   * Given a `moduleSpecifier` and `containingFile`, resolve the module and
    * return the `ModuleMetaData`.
    */
   resolveModule(
@@ -546,8 +521,7 @@ export class DenoCompiler
     return moduleMetaData;
   }
 
-  /**
+  /** Load and run a module and all of its dependencies based on a module
-   * Load and run a module and all of its dependencies based on a module
    * specifier and a containing file
    */
   run(
@@ -675,8 +649,7 @@ export class DenoCompiler
 
   // Deno specific static properties and methods
 
-  /**
+  /** Built in modules which can be returned to external modules
-   * Built in modules which can be returned to external modules
    *
    * Placed as a private static otherwise we get use before
    * declared with the `DenoCompiler`

js/console.ts

@@ -182,26 +182,35 @@ export class Console {
   // @internal
   constructor(private printFunc: PrintFunc) {}
 
+  /** Writes the arguments to stdout */
   // tslint:disable-next-line:no-any
   log = (...args: any[]): void => {
     this.printFunc(stringifyArgs(args));
   };
 
+  /** Writes the arguments to stdout */
   debug = this.log;
+  /** Writes the arguments to stdout */
   info = this.log;
 
+  /** Writes the properties of the supplied `obj` to stdout */
   // tslint:disable-next-line:no-any
   dir = (obj: any, options: ConsoleOptions = {}) => {
     this.printFunc(stringifyArgs([obj], options));
   };
 
+  /** Writes the arguments to stdout */
   // tslint:disable-next-line:no-any
   warn = (...args: any[]): void => {
     this.printFunc(stringifyArgs(args), true);
   };
 
+  /** Writes the arguments to stdout */
   error = this.warn;
 
+  /** Writes an error message to stdout if the assertion is `false`. If the
+   * assertion is `true`, nothing happens.
+   */
   // tslint:disable-next-line:no-any
   assert = (condition: boolean, ...args: any[]): void => {
     if (!condition) {

js/copy_file.ts

@@ -3,29 +3,30 @@ import * as msg from "gen/msg_generated";
 import { flatbuffers } from "flatbuffers";
 import * as dispatch from "./dispatch";
 
-/**
+/** Copies the contents of a file to another by name synchronously.
- * Copies the contents of a file to another by name synchronously.
  * Creates a new file if target does not exists, and if target exists,
  * overwrites original content of the target file.
+ *
  * It would also copy the permission of the original file
  * to the destination.
  *
- *     import { copyFileSync } from "deno";
+ *       import { copyFileSync } from "deno";
- *     copyFileSync("from.txt", "to.txt");
+ *       copyFileSync("from.txt", "to.txt");
  */
 export function copyFileSync(from: string, to: string): void {
   dispatch.sendSync(...req(from, to));
 }
 
-/**
+/** Copies the contents of a file to another by name.
- * Copies the contents of a file to another by name.
+ *
  * Creates a new file if target does not exists, and if target exists,
  * overwrites original content of the target file.
+ *
  * It would also copy the permission of the original file
  * to the destination.
  *
- *     import { copyFile } from "deno";
+ *       import { copyFile } from "deno";
- *     await copyFile("from.txt", "to.txt");
+ *       await copyFile("from.txt", "to.txt");
  */
 export async function copyFile(from: string, to: string): Promise<void> {
   await dispatch.sendAsync(...req(from, to));

js/dom_types.ts

@@ -245,28 +245,68 @@ export interface FormData {
   ): void;
 }
 
+/** A blob object represents a file-like object of immutable, raw data. */
 export interface Blob {
+  /** The size, in bytes, of the data contained in the `Blob` object. */
   readonly size: number;
+  /** A string indicating the media type of the data contained in the `Blob`.
+   * If the type is unknown, this string is empty.
+   */
   readonly type: string;
+  /** Returns a new `Blob` object containing the data in the specified range of
+   * bytes of the source `Blob`.
+   */
   slice(start?: number, end?: number, contentType?: string): Blob;
 }
 
 interface Body {
+  /** A simple getter used to expose a `ReadableStream` of the body contents. */
   readonly body: ReadableStream | null;
+  /** Stores a `Boolean` that declares whether the body has been used in a
+   * response yet.
+   */
   readonly bodyUsed: boolean;
+  /** Takes a `Response` stream and reads it to completion. It returns a promise
+   * that resolves with an `ArrayBuffer`.
+   */
   arrayBuffer(): Promise<ArrayBuffer>;
+  /** Takes a `Response` stream and reads it to completion. It returns a promise
+   * that resolves with a `Blob`.
+   */
   blob(): Promise<Blob>;
+  /** Takes a `Response` stream and reads it to completion. It returns a promise
+   * that resolves with a `FormData` object.
+   */
   formData(): Promise<FormData>;
+  /** Takes a `Response` stream and reads it to completion. It returns a promise
+   * that resolves with the result of parsing the body text as JSON.
+   */
   // tslint:disable-next-line:no-any
   json(): Promise<any>;
+  /** Takes a `Response` stream and reads it to completion. It returns a promise
+   * that resolves with a `USVString` (text).
+   */
   text(): Promise<string>;
 }
 
 export interface Headers {
+  /** Appends a new value onto an existing header inside a `Headers` object, or
+   * adds the header if it does not already exist.
+   */
   append(name: string, value: string): void;
+  /** Deletes a header from a `Headers` object. */
   delete(name: string): void;
+  /** Returns a `ByteString` sequence of all the values of a header within a
+   * `Headers` object with a given name.
+   */
   get(name: string): string | null;
+  /** Returns a boolean stating whether a `Headers` object contains a certain
+   * header.
+   */
   has(name: string): boolean;
+  /** Sets a new value for an existing header inside a Headers object, or adds
+   * the header if it does not already exist.
+   */
   set(name: string, value: string): void;
   forEach(
     callbackfn: (value: string, key: string, parent: Headers) => void,
@@ -336,100 +376,101 @@ export interface ResponseInit {
 }
 
 export interface Request extends Body {
-  /**
+  /** Returns the cache mode associated with request, which is a string
-   * Returns the cache mode associated with request,
+   * indicating how the the request will interact with the browser's cache when
-   * which is a string indicating how the the request will interact
+   * fetching.
-   * with the browser's cache when fetching.
    */
   readonly cache: RequestCache;
-  /**
+  /** Returns the credentials mode associated with request, which is a string
-   * Returns the credentials mode associated with request, which is a string
    * indicating whether credentials will be sent with the request always, never,
    * or only when sent to a same-origin URL.
    */
   readonly credentials: RequestCredentials;
-  /**
+  /** Returns the kind of resource requested by request, (e.g., `document` or
-   * Returns the kind of resource requested by request, e.g., "document" or
+   * `script`).
-   * "script".
    */
   readonly destination: RequestDestination;
-  /**
+  /** Returns a Headers object consisting of the headers associated with
-   * Returns a Headers object consisting of the headers associated with request.
+   * request.
+   *
    * Note that headers added in the network layer by the user agent
-   * will not be accounted for in this object, e.g., the "Host" header.
+   * will not be accounted for in this object, (e.g., the `Host` header).
    */
   readonly headers: Headers;
-  /**
+  /** Returns request's subresource integrity metadata, which is a cryptographic
-   * Returns request's subresource integrity metadata,
+   * hash of the resource being fetched. Its value consists of multiple hashes
-   * which is a cryptographic hash of the resource being fetched.
+   * separated by whitespace. [SRI]
-   * Its value consists of multiple hashes separated by whitespace. [SRI]
    */
   readonly integrity: string;
-  /**
+  /** Returns a boolean indicating whether or not request is for a history
-   * Returns a boolean indicating whether or not request is for a history
    * navigation (a.k.a. back-foward navigation).
    */
   readonly isHistoryNavigation: boolean;
-  /**
+  /** Returns a boolean indicating whether or not request is for a reload
-   * Returns a boolean indicating whether or not requestis for a
+   * navigation.
-   * reload navigation.
    */
   readonly isReloadNavigation: boolean;
-  /**
+  /** Returns a boolean indicating whether or not request can outlive the global
-   * Returns a boolean indicating whether or not request can outlive
+   * in which it was created.
-   * the global in which it was created.
    */
   readonly keepalive: boolean;
-  /**
+  /** Returns request's HTTP method, which is `GET` by default. */
-   * Returns request's HTTP method, which is "GET" by default.
-   */
   readonly method: string;
-  /**
+  /** Returns the mode associated with request, which is a string indicating
-   * Returns the mode associated with request, which is a string
+   * whether the request will use CORS, or will be restricted to same-origin
-   * indicating whether the request will use CORS, or will be
+   * URLs.
-   * restricted to same-origin URLs.
    */
   readonly mode: RequestMode;
-  /**
+  /** Returns the redirect mode associated with request, which is a string
-   * Returns the redirect mode associated with request, which is a string
    * indicating how redirects for the request will be handled during fetching.
+   *
    * A request will follow redirects by default.
    */
   readonly redirect: RequestRedirect;
-  /**
+  /** Returns the referrer of request. Its value can be a same-origin URL if
-   * Returns the referrer of request. Its value can be a same-origin URL if
    * explicitly set in init, the empty string to indicate no referrer, and
-   * "about:client" when defaulting to the global's default.
+   * `about:client` when defaulting to the global's default.
+   *
    * This is used during fetching to determine the value of the `Referer`
    * header of the request being made.
    */
   readonly referrer: string;
-  /**
+  /** Returns the referrer policy associated with request. This is used during
-   * Returns the referrer policy associated with request. This is used during
    * fetching to compute the value of the request's referrer.
    */
   readonly referrerPolicy: ReferrerPolicy;
-  /**
+  /** Returns the signal associated with request, which is an AbortSignal object
-   * Returns the signal associated with request, which is an AbortSignal
+   * indicating whether or not request has been aborted, and its abort event
-   * object indicating whether or not request has been aborted,
+   * handler.
-   * and its abort event handler.
    */
   readonly signal: AbortSignal;
-  /**
+  /** Returns the URL of request as a string. */
-   * Returns the URL of request as a string.
-   */
   readonly url: string;
   clone(): Request;
 }
 
 export interface Response extends Body {
+  /** Contains the `Headers` object associated with the response. */
   readonly headers: Headers;
+  /** Contains a boolean stating whether the response was successful (status in
+   * the range 200-299) or not.
+   */
   readonly ok: boolean;
+  /** Indicates whether or not the response is the result of a redirect; that
+   * is, its URL list has more than one entry.
+   */
   readonly redirected: boolean;
+  /** Contains the status code of the response (e.g., `200` for a success). */
   readonly status: number;
+  /** Contains the status message corresponding to the status code (e.g., `OK`
+   * for `200`).
+   */
   readonly statusText: string;
   readonly trailer: Promise<Headers>;
+  /** Contains the type of the response (e.g., `basic`, `cors`). */
   readonly type: ResponseType;
+  /** Contains the URL of the response. */
   readonly url: string;
+  /** Creates a clone of a `Response` object. */
   clone(): Response;
 }

js/errors.ts

@@ -1,6 +1,18 @@
 import { Base, ErrorKind } from "gen/msg_generated";
 export { ErrorKind } from "gen/msg_generated";
 
+/** A Deno specific error.  The `kind` property is set to a specific error code
+ * which can be used to in application logic.
+ *
+ *     import { DenoError, ErrorKind } from "deno";
+ *     try {
+ *       somethingThatMightThrow();
+ *     } catch (e) {
+ *       if (e instanceof DenoError && e.kind === DenoError.Overflow) {
+ *         console.error("Overflow error!");
+ *       }
+ *     }
+ */
 export class DenoError<T extends ErrorKind> extends Error {
   constructor(readonly kind: T, msg: string) {
     super(msg);

js/fetch.ts

@@ -178,6 +178,7 @@ class FetchResponse implements domTypes.Response {
   }
 }
 
+/** Fetch a resource from the network. */
 export async function fetch(
   input?: domTypes.Request | string,
   init?: domTypes.RequestInit

js/file_info.ts

@@ -1,8 +1,7 @@
 // Copyright 2018 the Deno authors. All rights reserved. MIT license.
 import * as msg from "gen/msg_generated";
 
-/**
+/** A FileInfo describes a file and is returned by `stat`, `lstat`,
- * A FileInfo describes a file and is returned by `stat`, `lstat`,
  * `statSync`, `lstatSync`.
  */
 export interface FileInfo {
@@ -10,52 +9,43 @@ export interface FileInfo {
   readonly _isSymlink: boolean;
   /** The size of the file, in bytes. */
   len: number;
-  /**
+  /** The last modification time of the file. This corresponds to the `mtime`
-   * The last modification time of the file. This corresponds to the `mtime`
    * field from `stat` on Unix and `ftLastWriteTime` on Windows. This may not
    * be available on all platforms.
    */
   modified: number | null;
-  /**
+  /** The last access time of the file. This corresponds to the `atime`
-   * The last access time of the file. This corresponds to the `atime`
    * field from `stat` on Unix and `ftLastAccessTime` on Windows. This may not
    * be available on all platforms.
    */
   accessed: number | null;
-  /**
+  /** The last access time of the file. This corresponds to the `birthtime`
-   * The last access time of the file. This corresponds to the `birthtime`
    * field from `stat` on Unix and `ftCreationTime` on Windows. This may not
    * be available on all platforms.
    */
   created: number | null;
-  /**
+  /** The underlying raw st_mode bits that contain the standard Unix permissions
-   * 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;
 
-  /**
+  /** Returns the file or directory name. */
-   * Returns the file or directory name.
-   */
   name: string | null;
 
-  /** Returns the file or directory path.  */
+  /** Returns the file or directory path. */
   path: string | null;
 
-  /**
+  /** Returns whether this is info for a regular file. This result is mutually
-   * Returns whether this is info for a regular file. This result is mutually
    * exclusive to `FileInfo.isDirectory` and `FileInfo.isSymlink`.
    */
   isFile(): boolean;
 
-  /**
+  /** Returns whether this is info for a regular directory. This result is
-   * Returns whether this is info for a regular directory. This result is
    * mutually exclusive to `FileInfo.isFile` and `FileInfo.isSymlink`.
    */
   isDirectory(): boolean;
 
-  /**
+  /** Returns whether this is info for a symlink. This result is
-   * Returns whether this is info for a symlink. This result is
    * mutually exclusive to `FileInfo.isFile` and `FileInfo.isDirectory`.
    */
   isSymlink(): boolean;

js/files.ts

@@ -6,6 +6,7 @@ import * as msg from "gen/msg_generated";
 import { assert } from "./util";
 import { flatbuffers } from "flatbuffers";
 
+/** The Deno abstraction for reading and writing files. */
 export class File implements Reader, Writer, Closer {
   constructor(readonly rid: number) {}
 
@@ -22,17 +23,30 @@ export class File implements Reader, Writer, Closer {
   }
 }
 
+/** An instance of `File` for stdin. */
 export const stdin = new File(0);
+/** An instance of `File` for stdout. */
 export const stdout = new File(1);
+/** An instance of `File` for stderr. */
 export const stderr = new File(2);
 
 // TODO This is just a placeholder - not final API.
 export type OpenMode = "r" | "w" | "w+" | "x";
 
+/** A factory function for creating instances of `File` associated with the
+ * supplied file name.
+ */
 export function create(filename: string): Promise<File> {
   return open(filename, "x");
 }
 
+/** Open a file and return an instance of the `File` object.
+ *
+ *       import * as deno from "deno";
+ *       (async () => {
+ *         const file = await deno.open("/foo/bar.txt");
+ *       })();
+ */
 export async function open(
   filename: string,
   mode: OpenMode = "r"
@@ -51,6 +65,10 @@ export async function open(
   return new File(rid);
 }
 
+/** Read from a file ID into an array buffer.
+ *
+ * Resolves with the `ReadResult` for the operation.
+ */
 export async function read(
   rid: number,
   p: ArrayBufferView
@@ -67,6 +85,10 @@ export async function read(
   return { nread: res.nread(), eof: res.eof() };
 }
 
+/** Write to the file ID the contents of the array buffer.
+ *
+ * Resolves with the number of bytes written.
+ */
 export async function write(rid: number, p: ArrayBufferView): Promise<number> {
   const builder = new flatbuffers.Builder();
   msg.Write.startWrite(builder);
@@ -80,6 +102,7 @@ export async function write(rid: number, p: ArrayBufferView): Promise<number> {
   return res.nbyte();
 }
 
+/** Close the file ID. */
 export function close(rid: number): void {
   const builder = new flatbuffers.Builder();
   msg.Close.startClose(builder);

js/global_eval.ts

@@ -1,5 +1,4 @@
-/**
+/** If you use the eval function indirectly, by invoking it via a reference
- * If you use the eval function indirectly, by invoking it via a reference
  * other than eval, as of ECMAScript 5 it works in the global scope rather than
  * the local scope. This means, for instance, that function declarations create
  * global functions, and that the code being evaluated doesn't have access to

js/io.ts

@@ -11,44 +11,46 @@ export interface ReadResult {
 // Reader is the interface that wraps the basic read() method.
 // https://golang.org/pkg/io/#Reader
 export interface Reader {
-  // read() reads up to p.byteLength bytes into p. It returns the number of
+  /** Reads up to p.byteLength bytes into `p`. It resolves to the number
-  // bytes read (0 <= n <= p.byteLength) and any error encountered. Even if
+   * of bytes read (`0` <= `n` <= `p.byteLength`) and any error encountered.
-  // read() returns n < p.byteLength, it may use all of p as scratch space
+   * Even if `read()` returns `n` < `p.byteLength`, it may use all of `p` as
-  // during the call. If some data is available but not p.byteLength bytes,
+   * scratch space during the call. If some data is available but not
-  // read() conventionally returns what is available instead of waiting for
+   * `p.byteLength` bytes, `read()` conventionally returns what is available
-  // more.
+   * instead of waiting for more.
-  //
+   *
-  // When read() encounters an error or end-of-file condition after successfully
+   * When `read()` encounters an error or end-of-file condition after
-  // reading n > 0 bytes, it returns the number of bytes read. It may return the
+   * successfully reading `n` > `0` bytes, it returns the number of bytes read.
-  // (non-nil) error from the same call or return the error (and n == 0) from a
+   * It may return the (non-nil) error from the same call or return the error
-  // subsequent call. An instance of this general case is that a Reader
+   * (and `n` == `0`) from a subsequent call. An instance of this general case
-  // returning a non-zero number of bytes at the end of the input stream may
+   * is that a `Reader` returning a non-zero number of bytes at the end of the
-  // return either err == EOF or err == nil. The next read() should return 0,
+   * input stream may return either `err` == `EOF` or `err` == `null`. The next
-  // EOF.
+   * `read()` should return `0`, `EOF`.
-  //
+   *
-  // Callers should always process the n > 0 bytes returned before considering
+   * Callers should always process the `n` > `0` bytes returned before
-  // the EOF. Doing so correctly handles I/O errors that happen after reading
+   * considering the `EOF`. Doing so correctly handles I/O errors that happen
-  // some bytes and also both of the allowed EOF behaviors.
+   * after reading some bytes and also both of the allowed `EOF` behaviors.
-  //
+   *
-  // Implementations of read() are discouraged from returning a zero byte count
+   * Implementations of `read()` are discouraged from returning a zero byte
-  // with a nil error, except when p.byteLength == 0. Callers should treat a
+   * count with a `null` error, except when `p.byteLength` == `0`. Callers
-  // return of 0 and nil as indicating that nothing happened; in particular it
+   * should treat a return of `0` and `null` as indicating that nothing
-  // does not indicate EOF.
+   * happened; in particular it does not indicate `EOF`.
-  //
+   *
-  // Implementations must not retain p.
+   * Implementations must not retain `p`.
+   */
   read(p: ArrayBufferView): Promise<ReadResult>;
 }
 
 // Writer is the interface that wraps the basic write() method.
 // https://golang.org/pkg/io/#Writer
 export interface Writer {
-  // write() writes p.byteLength bytes from p to the underlying data stream. It
+  /** Writes `p.byteLength` bytes from `p` to the underlying data
-  // returns the number of bytes written from p (0 <= n <= p.byteLength) and any
+   * stream. It resolves to the number of bytes written from `p` (`0` <= `n` <=
-  // error encountered that caused the write to stop early. write() must return
+   * `p.byteLength`) and any error encountered that caused the write to stop
-  // a non-nil error if it returns n < p.byteLength. write() must not modify the
+   * early. `write()` must return a non-null error if it returns `n` <
-  // slice data, even temporarily.
+   * `p.byteLength`. write() must not modify the slice data, even temporarily.
-  //
+   *
-  // Implementations must not retain p.
+   * Implementations must not retain `p`.
+   */
   write(p: ArrayBufferView): Promise<number>;
 }
 
@@ -61,15 +63,16 @@ 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
+  /** Seek sets the offset for the next `read()` or `write()` to offset,
-  // according to whence: SeekStart means relative to the start of the file,
+   * interpreted according to `whence`: `SeekStart` means relative to the start
-  // SeekCurrent means relative to the current offset, and SeekEnd means
+   * of the file, `SeekCurrent` means relative to the current offset, and
-  // relative to the end. Seek returns the new offset relative to the start of
+   * `SeekEnd` means relative to the end. Seek returns the new offset relative
-  // the file and an error, if any.
+   * 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
+   * 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 operations
-  // on the underlying object is implementation-dependent.
+   * on the underlying object is implementation-dependent.
+   */
   seek(offset: number, whence: number): Promise<void>;
 }
 
@@ -91,17 +94,17 @@ export interface ReadWriteCloser extends Reader, Writer, Closer {}
 // https://golang.org/pkg/io/#ReadWriteSeeker
 export interface ReadWriteSeeker extends Reader, Writer, Seeker {}
 
-// copy() copies from src to dst until either EOF is reached on src or an error
+/** Copies from `src` to `dst` until either `EOF` is reached on `src`
-// occurs. It returns the number of bytes copied and the first error encountered
+ * or an error occurs. It returns the number of bytes copied and the first
-// while copying, if any.
+ * error encountered while copying, if any.
-//
+ *
-// Because copy() is defined to read from src until EOF, it does not treat an
+ * Because `copy()` is defined to read from `src` until `EOF`, it does not
-// EOF from read() as an error to be reported.
+ * treat an `EOF` from `read()` as an error to be reported.
-//
+ */
 // https://golang.org/pkg/io/#Copy
 export async function copy(dst: Writer, src: Reader): Promise<number> {
   let n = 0;
-  const b = new Uint8Array(32*1024);
+  const b = new Uint8Array(32 * 1024);
   let gotEOF = false;
   while (gotEOF === false) {
     const result = await src.read(b);

js/make_temp_dir.ts

@@ -10,19 +10,17 @@ export interface MakeTempDirOptions {
   suffix?: string;
 }
 
-/**
+/** makeTempDirSync is the synchronous version of `makeTempDir`.
- * makeTempDirSync is the synchronous version of `makeTempDir`.
  *
- *     import { makeTempDirSync } from "deno";
+ *       import { makeTempDirSync } from "deno";
- *     const tempDirName0 = makeTempDirSync();
+ *       const tempDirName0 = makeTempDirSync();
- *     const tempDirName1 = makeTempDirSync({ prefix: 'my_temp' });
+ *       const tempDirName1 = makeTempDirSync({ prefix: 'my_temp' });
  */
 export function makeTempDirSync(options: MakeTempDirOptions = {}): string {
   return res(dispatch.sendSync(...req(options)));
 }
 
-/**
+/** makeTempDir creates a new temporary directory in the directory `dir`, its
- * makeTempDir creates a new temporary directory in the directory `dir`, its
  * name beginning with `prefix` and ending with `suffix`.
  * It returns the full path to the newly created directory.
  * If `dir` is unspecified, tempDir uses the default directory for temporary
@@ -30,9 +28,9 @@ export function makeTempDirSync(options: MakeTempDirOptions = {}): string {
  * same directory. It is the caller's responsibility to remove the directory
  * when no longer needed.
  *
- *     import { makeTempDir } from "deno";
+ *       import { makeTempDir } from "deno";
- *     const tempDirName0 = await makeTempDir();
+ *       const tempDirName0 = await makeTempDir();
- *     const tempDirName1 = await makeTempDir({ prefix: 'my_temp' });
+ *       const tempDirName1 = await makeTempDir({ prefix: 'my_temp' });
  */
 export async function makeTempDir(
   options: MakeTempDirOptions = {}

js/metrics.ts

@@ -12,6 +12,7 @@ interface Metrics {
   bytesReceived: number;
 }
 
+/** Receive metrics from the privileged side of Deno. */
 export function metrics(): Metrics {
   return res(dispatch.sendSync(...req()));
 }

js/mkdir.ts

@@ -3,21 +3,20 @@ import * as msg from "gen/msg_generated";
 import { flatbuffers } from "flatbuffers";
 import * as dispatch from "./dispatch";
 
-/**
+/** Creates a new directory with the specified path and permission
- * Creates a new directory with the specified path and permission synchronously.
+ * synchronously.
  *
- *     import { mkdirSync } from "deno";
+ *       import { mkdirSync } from "deno";
- *     mkdirSync("new_dir");
+ *       mkdirSync("new_dir");
  */
 export function mkdirSync(path: string, mode = 0o777): void {
   dispatch.sendSync(...req(path, mode));
 }
 
-/**
+/** Creates a new directory with the specified path and permission.
- * Creates a new directory with the specified path and permission.
  *
- *     import { mkdir } from "deno";
+ *       import { mkdir } from "deno";
- *     await mkdir("new_dir");
+ *       await mkdir("new_dir");
  */
 export async function mkdir(path: string, mode = 0o777): Promise<void> {
   await dispatch.sendAsync(...req(path, mode));

js/net.ts

@@ -16,14 +16,15 @@ export type Addr = string;
 
 /** A Listener is a generic network listener for stream-oriented protocols. */
 export interface Listener {
-  /** accept() waits for and returns the next connection to the Listener. */
+  /** Waits for and resolves to the next connection to the `Listener`. */
   accept(): Promise<Conn>;
 
-  /** Close closes the listener.
+  /** Close closes the listener. Any pending accept promises will be rejected
-   * Any pending accept promises will be rejected with errors.
+   * with errors.
    */
   close(): void;
 
+  /** Return the address of the `Listener`. */
   addr(): Addr;
 }
 
@@ -53,9 +54,17 @@ class ListenerImpl implements Listener {
 }
 
 export interface Conn extends Reader, Writer, Closer {
+  /** The local address of the connection. */
   localAddr: string;
+  /** The remote address of the connection. */
   remoteAddr: string;
+  /** Shuts down (`shutdown(2)`) the reading side of the TCP connection. Most
+   * callers should just use `close()`.
+   */
   closeRead(): void;
+  /** Shuts down (`shutdown(2)`) the writing side of the TCP connection. Most
+   * callers should just use `close()`.
+   */
   closeWrite(): void;
 }
 
@@ -113,18 +122,18 @@ function shutdown(rid: number, how: ShutdownMode) {
 
 /** Listen announces on the local network address.
  *
- * The network must be "tcp", "tcp4", "tcp6", "unix" or "unixpacket".
+ * The network must be `tcp`, `tcp4`, `tcp6`, `unix` or `unixpacket`.
  *
  * For TCP networks, if the host in the address parameter is empty or a literal
- * unspecified IP address, Listen listens on all available unicast and anycast
+ * unspecified IP address, `listen()` listens on all available unicast and
- * IP addresses of the local system. To only use IPv4, use network "tcp4". The
+ * anycast IP addresses of the local system. To only use IPv4, use network
- * address can use a host name, but this is not recommended, because it will
+ * `tcp4`. The address can use a host name, but this is not recommended,
- * create a listener for at most one of the host's IP addresses. If the port in
+ * because it will create a listener for at most one of the host's IP
- * the address parameter is empty or "0", as in "127.0.0.1:" or "[::1]:0", a
+ * addresses. If the port in the address parameter is empty or `0`, as in
- * port number is automatically chosen. The Addr method of Listener can be used
+ * `127.0.0.1:` or `[::1]:0`, a port number is automatically chosen. The
- * to discover the chosen port.
+ * `addr()` method of `Listener` can be used to discover the chosen port.
  *
- * See dial() for a description of the network and address parameters.
+ * See `dial()` for a description of the network and address parameters.
  */
 export function listen(network: Network, address: string): Listener {
   const builder = new flatbuffers.Builder();
@@ -144,16 +153,17 @@ export function listen(network: Network, address: string): Listener {
 
 /** Dial connects to the address on the named network.
  *
- * Supported networks are only "tcp" currently.
+ * Supported networks are only `tcp` currently.
- * TODO: "tcp4" (IPv4-only), "tcp6" (IPv6-only), "udp", "udp4"
- * (IPv4-only), "udp6" (IPv6-only), "ip", "ip4" (IPv4-only), "ip6" (IPv6-only),
- * "unix", "unixgram" and "unixpacket".
  *
- * For TCP and UDP networks, the address has the form "host:port". The host must
+ * TODO: `tcp4` (IPv4-only), `tcp6` (IPv6-only), `udp`, `udp4` (IPv4-only),
+ * `udp6` (IPv6-only), `ip`, `ip4` (IPv4-only), `ip6` (IPv6-only), `unix`,
+ * `unixgram` and `unixpacket`.
+ *
+ * For TCP and UDP networks, the address has the form `host:port`. The host must
  * be a literal IP address, or a host name that can be resolved to IP addresses.
  * The port must be a literal port number or a service name. If the host is a
  * literal IPv6 address it must be enclosed in square brackets, as in
- * "[2001:db8::1]:80" or "[fe80::1%zone]:80". The zone specifies the scope of
+ * `[2001:db8::1]:80` or `[fe80::1%zone]:80`. The zone specifies the scope of
  * the literal IPv6 address as defined in RFC 4007. The functions JoinHostPort
  * and SplitHostPort manipulate a pair of host and port in this form. When using
  * TCP, and the host resolves to multiple IP addresses, Dial will try each IP
@@ -161,12 +171,12 @@ export function listen(network: Network, address: string): Listener {
  *
  * Examples:
  *
- *   dial("tcp", "golang.org:http")
+ *     dial("tcp", "golang.org:http")
- *   dial("tcp", "192.0.2.1:http")
+ *     dial("tcp", "192.0.2.1:http")
- *   dial("tcp", "198.51.100.1:80")
+ *     dial("tcp", "198.51.100.1:80")
- *   dial("udp", "[2001:db8::1]:domain")
+ *     dial("udp", "[2001:db8::1]:domain")
- *   dial("udp", "[fe80::1%lo0]:53")
+ *     dial("udp", "[fe80::1%lo0]:53")
- *   dial("tcp", ":80")
+ *     dial("tcp", ":80")
  */
 export async function dial(network: Network, address: string): Promise<Conn> {
   const builder = new flatbuffers.Builder();
@@ -184,7 +194,7 @@ export async function dial(network: Network, address: string): Promise<Conn> {
   return new ConnImpl(res.rid(), res.remoteAddr()!, res.localAddr()!);
 }
 
-// Unused but reserved op.
+/** **RESERVED** */
 export async function connect(
   network: Network,
   address: string

js/os.ts

@@ -6,6 +6,7 @@ import * as util from "./util";
 import { flatbuffers } from "flatbuffers";
 import { sendSync } from "./dispatch";
 
+/** Exit the Deno process with optional exit code. */
 export function exit(exitCode = 0): never {
   const builder = new flatbuffers.Builder();
   msg.Exit.startExit(builder);
@@ -93,18 +94,18 @@ function setEnv(key: string, value: string): void {
   sendSync(builder, msg.Any.SetEnv, inner);
 }
 
-/**
+/** Returns a snapshot of the environment variables at invocation. Mutating a
- * Returns a snapshot of the environment variables at invocation. Mutating a
  * property in the object will set that variable in the environment for
  * the process. The environment object will only accept `string`s or `number`s
  * as values.
- *     import { env } from "deno";
  *
- *     const myEnv = env();
+ *       import { env } from "deno";
- *     console.log(myEnv.SHELL);
+ *
- *     myEnv.TEST_VAR = "HELLO";
+ *       const myEnv = env();
- *     const newEnv = env();
+ *       console.log(myEnv.SHELL);
- *     console.log(myEnv.TEST_VAR == newEnv.TEST_VAR);
+ *       myEnv.TEST_VAR = "HELLO";
+ *       const newEnv = env();
+ *       console.log(myEnv.TEST_VAR == newEnv.TEST_VAR);
  */
 export function env(): { [index: string]: string } {
   /* Ideally we could write

js/platform.ts

@@ -1,13 +1,9 @@
 // Do not add unsupported platforms.
 export interface Platform {
-  /**
+  /** The operating system CPU architecture. */
-   * The operating system CPU architecture
-   */
   arch: "x64";
 
-  /**
+  /** The operating system platform. */
-   * The operating system platform
-   */
   os: "mac" | "win" | "linux";
 }
 

js/read_dir.ts

@@ -5,23 +5,20 @@ import * as dispatch from "./dispatch";
 import { FileInfo, FileInfoImpl } from "./file_info";
 import { assert } from "./util";
 
-/**
+/** Reads the directory given by path and returns a list of file info
- * Reads the directory given by path and returns
+ * synchronously.
- * a list of file info synchronously.
  *
- *     import { readDirSync } from "deno";
+ *       import { readDirSync } from "deno";
- *     const files = readDirSync("/");
+ *       const files = readDirSync("/");
  */
 export function readDirSync(path: string): FileInfo[] {
   return res(dispatch.sendSync(...req(path)));
 }
 
-/**
+/** Reads the directory given by path and returns a list of file info.
- * Reads the directory given by path and returns a list of file info.
- *
- *     import { readDir } from "deno";
- *     const files = await readDir("/");
  *
+ *       import { readDir } from "deno";
+ *       const files = await readDir("/");
  */
 export async function readDir(path: string): Promise<FileInfo[]> {
   return res(await dispatch.sendAsync(...req(path)));

js/read_file.ts

@@ -4,25 +4,23 @@ import { flatbuffers } from "flatbuffers";
 import { assert } from "./util";
 import * as dispatch from "./dispatch";
 
-/**
+/** Read the entire contents of a file synchronously.
- * Read the entire contents of a file synchronously.
  *
- *     import { readFileSync } from "deno";
+ *       import { readFileSync } from "deno";
- *     const decoder = new TextDecoder("utf-8");
+ *       const decoder = new TextDecoder("utf-8");
- *     const data = readFileSync("hello.txt");
+ *       const data = readFileSync("hello.txt");
- *     console.log(decoder.decode(data));
+ *       console.log(decoder.decode(data));
  */
 export function readFileSync(filename: string): Uint8Array {
   return res(dispatch.sendSync(...req(filename)));
 }
 
-/**
+/** Read the entire contents of a file.
- * Read the entire contents of a file.
  *
- *     import { readFile } from "deno";
+ *       import { readFile } from "deno";
- *     const decoder = new TextDecoder("utf-8");
+ *       const decoder = new TextDecoder("utf-8");
- *     const data = await readFile("hello.txt");
+ *       const data = await readFile("hello.txt");
- *     console.log(decoder.decode(data));
+ *       console.log(decoder.decode(data));
  */
 export async function readFile(filename: string): Promise<Uint8Array> {
   return res(await dispatch.sendAsync(...req(filename)));

js/read_link.ts

@@ -4,21 +4,19 @@ import { flatbuffers } from "flatbuffers";
 import { assert } from "./util";
 import * as dispatch from "./dispatch";
 
-/**
+/** Returns the destination of the named symbolic link synchronously.
- * Returns the destination of the named symbolic link synchronously.
  *
- *     import { readlinkSync } from "deno";
+ *       import { readlinkSync } from "deno";
- *     const targetPath = readlinkSync("symlink/path");
+ *       const targetPath = readlinkSync("symlink/path");
  */
 export function readlinkSync(name: string): string {
   return res(dispatch.sendSync(...req(name)));
 }
 
-/**
+/** Returns the destination of the named symbolic link.
- * Returns the destination of the named symbolic link.
  *
- *     import { readlink } from "deno";
+ *       import { readlink } from "deno";
- *     const targetPath = await readlink("symlink/path");
+ *       const targetPath = await readlink("symlink/path");
  */
 export async function readlink(name: string): Promise<string> {
   return res(await dispatch.sendAsync(...req(name)));

js/remove.ts

@@ -3,47 +3,41 @@ import * as msg from "gen/msg_generated";
 import { flatbuffers } from "flatbuffers";
 import * as dispatch from "./dispatch";
 
-/**
+/** Removes the named file or (empty) directory synchronously. Would throw
- * Removes the named file or (empty) directory synchronously.
+ * error if permission denied, not found, or directory not empty.
- * Would throw error if permission denied, not found, or
- * directory not empty.
  *
- *     import { removeSync } from "deno";
+ *       import { removeSync } from "deno";
- *     removeSync("/path/to/empty_dir/or/file");
+ *       removeSync("/path/to/empty_dir/or/file");
  */
 export function removeSync(path: string): void {
   dispatch.sendSync(...req(path, false));
 }
 
-/**
+/** Removes the named file or (empty) directory. Would throw error if
- * Removes the named file or (empty) directory.
+ * permission denied, not found, or directory not empty.
- * Would throw error if permission denied, not found, or
- * directory not empty.
  *
- *     import { remove } from "deno";
+ *       import { remove } from "deno";
- *     await remove("/path/to/empty_dir/or/file");
+ *       await remove("/path/to/empty_dir/or/file");
  */
 export async function remove(path: string): Promise<void> {
   await dispatch.sendAsync(...req(path, false));
 }
 
-/**
+/** Recursively removes the named file or directory synchronously.  Would throw
- * Recursively removes the named file or directory synchronously.
+ * error if permission denied or not found.
- * Would throw error if permission denied or not found
  *
- *     import { removeAllSync } from "deno";
+ *       import { removeAllSync } from "deno";
- *     removeAllSync("/path/to/dir/or/file");
+ *       removeAllSync("/path/to/dir/or/file");
  */
 export function removeAllSync(path: string): void {
   dispatch.sendSync(...req(path, true));
 }
 
-/**
+/** Recursively removes the named file or directory. Would throw error if
- * Recursively removes the named file or directory.
+ * permission denied or not found.
- * Would throw error if permission denied or not found
  *
- *     import { removeAll } from "deno";
+ *       import { removeAll } from "deno";
- *     await removeAll("/path/to/dir/or/file");
+ *       await removeAll("/path/to/dir/or/file");
  */
 export async function removeAll(path: string): Promise<void> {
   await dispatch.sendAsync(...req(path, true));

js/rename.ts

@@ -3,25 +3,24 @@ import * as msg from "gen/msg_generated";
 import { flatbuffers } from "flatbuffers";
 import * as dispatch from "./dispatch";
 
-/**
+/** Synchronously renames (moves) `oldpath` to `newpath`. If `newpath` already
- * Synchronously renames (moves) oldpath to newpath. If newpath already exists
+ * exists and is not a directory, `renameSync()` replaces it. OS-specific
- * and is not a directory, Rename replaces it. OS-specific restrictions may
+ * restrictions may apply when `oldpath` and `newpath` are in different
- * apply when oldpath and newpath are in different directories.
+ * directories.
  *
- *     import { renameSync } from "deno";
+ *       import { renameSync } from "deno";
- *     renameSync("old/path", "new/path");
+ *       renameSync("old/path", "new/path");
  */
 export function renameSync(oldpath: string, newpath: string): void {
   dispatch.sendSync(...req(oldpath, newpath));
 }
 
-/**
+/** Renames (moves) `oldpath` to `newpath`. If `newpath` already exists and is
- * Renames (moves) oldpath to newpath. If newpath already exists
+ * not a directory, `rename()` replaces it. OS-specific restrictions may apply
- * and is not a directory, Rename replaces it. OS-specific restrictions may
+ * when `oldpath` and `newpath` are in different directories.
- * apply when oldpath and newpath are in different directories.
  *
- *     import { rename } from "deno";
+ *       import { rename } from "deno";
- *     await rename("old/path", "new/path");
+ *       await rename("old/path", "new/path");
  */
 export async function rename(oldpath: string, newpath: string): Promise<void> {
   await dispatch.sendAsync(...req(oldpath, newpath));

js/stat.ts

@@ -5,51 +5,46 @@ import * as dispatch from "./dispatch";
 import { assert } from "./util";
 import { FileInfo, FileInfoImpl } from "./file_info";
 
-/**
+/** Queries the file system for information on the path provided. If the given
- * Queries the file system for information on the path provided.
+ * path is a symlink information about the symlink will be returned.
- * If the given path is a symlink information about the symlink will
- * be returned.
  *
- *     import { lstat } from "deno";
+ *       import { lstat } from "deno";
- *     const fileInfo = await lstat("hello.txt");
+ *       const fileInfo = await lstat("hello.txt");
- *     assert(fileInfo.isFile());
+ *       assert(fileInfo.isFile());
  */
 export async function lstat(filename: string): Promise<FileInfo> {
   return res(await dispatch.sendAsync(...req(filename, true)));
 }
 
-/**
+/** Queries the file system for information on the path provided synchronously.
- * Queries the file system for information on the path provided synchronously.
+ * If the given path is a symlink information about the symlink will be
- * If the given path is a symlink information about the symlink will
+ * returned.
- * be returned.
  *
- *     import { lstatSync } from "deno";
+ *       import { lstatSync } from "deno";
- *     const fileInfo = lstatSync("hello.txt");
+ *       const fileInfo = lstatSync("hello.txt");
- *     assert(fileInfo.isFile());
+ *       assert(fileInfo.isFile());
  */
 export function lstatSync(filename: string): FileInfo {
   return res(dispatch.sendSync(...req(filename, true)));
 }
 
-/**
+/** Queries the file system for information on the path provided. `stat` Will
- * Queries the file system for information on the path provided.
+ * always follow symlinks.
- * `stat` Will always follow symlinks.
  *
- *     import { stat } from "deno";
+ *       import { stat } from "deno";
- *     const fileInfo = await stat("hello.txt");
+ *       const fileInfo = await stat("hello.txt");
- *     assert(fileInfo.isFile());
+ *       assert(fileInfo.isFile());
  */
 export async function stat(filename: string): Promise<FileInfo> {
   return res(await dispatch.sendAsync(...req(filename, false)));
 }
 
-/**
+/** Queries the file system for information on the path provided synchronously.
- * Queries the file system for information on the path provided synchronously.
  * `statSync` Will always follow symlinks.
  *
- *     import { statSync } from "deno";
+ *       import { statSync } from "deno";
- *     const fileInfo = statSync("hello.txt");
+ *       const fileInfo = statSync("hello.txt");
- *     assert(fileInfo.isFile());
+ *       assert(fileInfo.isFile());
  */
 export function statSync(filename: string): FileInfo {
   return res(dispatch.sendSync(...req(filename, false)));

js/symlink.ts

@@ -4,13 +4,12 @@ import { flatbuffers } from "flatbuffers";
 import * as dispatch from "./dispatch";
 import * as util from "./util";
 
-/**
+/** Synchronously creates `newname` as a symbolic link to `oldname`. The type
- * Synchronously creates newname as a symbolic link to oldname.
+ * argument can be set to `dir` or `file` and is only available on Windows
- * The type argument can be set to 'dir' or 'file' and is only
+ * (ignored on other platforms).
- * available on Windows (ignored on other platforms).
  *
- *     import { symlinkSync } from "deno";
+ *       import { symlinkSync } from "deno";
- *     symlinkSync("old/name", "new/name");
+ *       symlinkSync("old/name", "new/name");
  */
 export function symlinkSync(
   oldname: string,
@@ -20,13 +19,12 @@ export function symlinkSync(
   dispatch.sendSync(...req(oldname, newname, type));
 }
 
-/**
+/** Creates `newname` as a symbolic link to `oldname`. The type argument can be
- * Creates newname as a symbolic link to oldname.
+ * set to `dir` or `file` and is only available on Windows (ignored on other
- * The type argument can be set to 'dir' or 'file' and is only
+ * platforms).
- * available on Windows (ignored on other platforms).
  *
- *     import { symlink } from "deno";
+ *       import { symlink } from "deno";
- *     await symlink("old/name", "new/name");
+ *       await symlink("old/name", "new/name");
  */
 export async function symlink(
   oldname: string,

js/text_encoding.ts

@@ -2,6 +2,7 @@
 import * as base64 from "base64-js";
 import { DenoError, ErrorKind } from "./errors";
 
+/** Decodes a string of data which has been encoded using base-64. */
 export function atob(s: string): string {
   const rem = s.length % 4;
   // base64-js requires length exactly times of 4
@@ -24,6 +25,7 @@ export function atob(s: string): string {
   return result;
 }
 
+/** Creates a base-64 ASCII string from the input string. */
 export function btoa(s: string): string {
   const byteArray = [];
   for (let i = 0; i < s.length; i++) {

js/timers.ts

@@ -197,6 +197,7 @@ function setTimer<Args extends Array<unknown>>(
   return timer.id;
 }
 
+/** Sets a timer which executes a function once after the timer expires. */
 export function setTimeout<Args extends Array<unknown>>(
   cb: (...args: Args) => void,
   delay: number,
@@ -205,6 +206,7 @@ export function setTimeout<Args extends Array<unknown>>(
   return setTimer(cb, delay, args, false);
 }
 
+/** Repeatedly calls a function , with a fixed time delay between each call. */
 export function setInterval<Args extends Array<unknown>>(
   cb: (...args: Args) => void,
   delay: number,
@@ -213,6 +215,7 @@ export function setInterval<Args extends Array<unknown>>(
   return setTimer(cb, delay, args, true);
 }
 
+/** Clears a previously set timer by id. */
 export function clearTimer(id: number): void {
   const timer = idMap.get(id);
   if (timer === undefined) {

js/trace.ts

@@ -55,17 +55,16 @@ export function maybePushTrace(op: msg.Any, sync: boolean): void {
   );
 }
 
-/**
+/** Trace privileged operations executed inside a given function or promise.
- * Trace operations executed inside a given function or promise.
+ *
- * Notice: To capture every operation in asynchronous deno.* calls,
+ * _Notice:_ To capture every operation in asynchronous `deno.*` calls,
  * you might want to put them in functions instead of directly invoking.
  *
- *     import { trace, mkdir } from "deno";
+ *       import { trace, mkdir } from "deno";
  *
- *     const ops = await trace(async () => {
+ *       const ops = await trace(async () => {
- *       await mkdir("my_dir");
+ *         await mkdir("my_dir");
- *     });
+ *       });
- *     // ops becomes [{ sync: false, name: "Mkdir" }]
  */
 export async function trace(
   // tslint:disable-next-line:no-any

js/truncate.ts

@@ -3,25 +3,24 @@ import * as msg from "gen/msg_generated";
 import { flatbuffers } from "flatbuffers";
 import * as dispatch from "./dispatch";
 
-/**
+/** Truncates or extends the specified file synchronously, updating the size of
- * Truncates or extends the specified file synchronously,
+ * this file to become size.
- * updating the size of this file to become size.
  *
- *     import { truncateSync } from "deno";
+ *       import { truncateSync } from "deno";
  *
- *     truncateSync("hello.txt", 10);
+ *       truncateSync("hello.txt", 10);
  */
 export function truncateSync(name: string, len?: number): void {
   dispatch.sendSync(...req(name, len));
 }
 
 /**
- * Truncates or extends the specified file,
+ * Truncates or extends the specified file, updating the size of this file to
- * updating the size of this file to become size.
+ * become size.
  *
- *     import { truncate } from "deno";
+ *       import { truncate } from "deno";
  *
- *     await truncate("hello.txt", 10);
+ *       await truncate("hello.txt", 10);
  */
 export async function truncate(name: string, len?: number): Promise<void> {
   await dispatch.sendAsync(...req(name, len));

js/types.ts

@@ -41,82 +41,60 @@ export interface ModuleInfo {
 // tslint:enable:max-line-length
 
 export interface CallSite {
-  /**
+  /** Value of `this` */
-   * Value of "this"
-   */
   // tslint:disable-next-line:no-any
   getThis(): any;
 
-  /**
+  /** Type of `this` as a string.
-   * Type of "this" as a string.
+   *
    * This is the name of the function stored in the constructor field of
-   * "this", if available.  Otherwise the object's [[Class]] internal
+   * `this`, if available.  Otherwise the object's `[[Class]]` internal
    * property.
    */
   getTypeName(): string | null;
 
-  /**
+  /** Current function. */
-   * Current function
-   */
   getFunction(): Function | undefined;
 
-  /**
+  /** Name of the current function, typically its name property.
-   * Name of the current function, typically its name property.
+   *
    * If a name property is not available an attempt will be made to try
    * to infer a name from the function's context.
    */
   getFunctionName(): string | null;
 
-  /**
+  /** Name of the property (of `this` or one of its prototypes) that holds
-   * Name of the property [of "this" or one of its prototypes] that holds
+   * the current function.
-   * the current function
    */
   getMethodName(): string | null;
 
-  /**
+  /** Name of the script (if this function was defined in a script). */
-   * Name of the script [if this function was defined in a script]
-   */
   getFileName(): string | null;
 
-  /**
+  /** Get the script name or source URL for the source map. */
-   * Get the script name or source URL for the source map
-   */
   getScriptNameOrSourceURL(): string;
 
-  /**
+  /** Current line number (if this function was defined in a script). */
-   * Current line number [if this function was defined in a script]
-   */
   getLineNumber(): number | null;
 
-  /**
+  /** Current column number (if this function was defined in a script). */
-   * Current column number [if this function was defined in a script]
-   */
   getColumnNumber(): number | null;
 
-  /**
+  /** A call site object representing the location where eval was called (if
-   * A call site object representing the location where eval was called
+   * this function was created using a call to `eval`)
-   * [if this function was created using a call to eval]
    */
   getEvalOrigin(): string | undefined;
 
-  /**
+  /** Is this a top level invocation, that is, is `this` the global object? */
-   * Is this a toplevel invocation, that is, is "this" the global object?
-   */
   isToplevel(): boolean;
 
-  /**
+  /** Does this call take place in code defined by a call to `eval`? */
-   * Does this call take place in code defined by a call to eval?
-   */
   isEval(): boolean;
 
-  /**
+  /** Is this call in native V8 code? */
-   * Is this call in native V8 code?
-   */
   isNative(): boolean;
 
-  /**
+  /** Is this a constructor call? */
-   * Is this a constructor call?
-   */
   isConstructor(): boolean;
 }
 
@@ -136,7 +114,7 @@ export interface RawSourceMap extends StartOfSourceMap {
 declare global {
   // Declare "static" methods in Error
   interface ErrorConstructor {
-    /** Create .stack property on a target object */
+    /** Create `.stack` property on a target object */
     captureStackTrace(targetObject: object, constructorOpt?: Function): void;
 
     // tslint:disable:max-line-length

js/util.ts

@@ -8,8 +8,7 @@ export function setLogDebug(debug: boolean): void {
   logDebug = debug;
 }
 
-/**
+/** Debug logging for deno.
- * Debug logging for deno.
  * Enable with the `--log-debug` or `-D` command line flag.
  * @internal
  */
@@ -38,20 +37,22 @@ export function arrayToStr(ui8: Uint8Array): string {
   return String.fromCharCode(...ui8);
 }
 
-/**
+/** A `Resolvable` is a Promise with the `reject` and `resolve` functions
- * A `Resolvable` is a Promise with the `reject` and `resolve` functions
  * placed as methods on the promise object itself. It allows you to do:
  *
- *     const p = createResolvable<number>();
+ *       const p = createResolvable<number>();
- *     ...
+ *       // ...
- *     p.resolve(42);
+ *       p.resolve(42);
  *
- * It'd be prettier to make Resolvable a class that inherits from Promise,
+ * It'd be prettier to make `Resolvable` a class that inherits from `Promise`,
  * rather than an interface. This is possible in ES2016, however typescript
  * produces broken code when targeting ES5 code.
- * See https://github.com/Microsoft/TypeScript/issues/15202
- * At the time of writing, the github issue is closed but the problem remains.
  *
+ * At the time of writing, the GitHub issue is closed in favour of a proposed
+ * solution that is awaiting feedback.
+ *
+ * @see https://github.com/Microsoft/TypeScript/issues/15202
+ * @see https://github.com/Microsoft/TypeScript/issues/15397
  * @internal
  */
 
@@ -109,11 +110,8 @@ export interface Deferred {
   reject: Function;
 }
 
-/**
+/** Create a wrapper around a promise that could be resolved externally. */
- * Create a wrapper around a promise that could be
+// @internal
- * resolved externally.
- * @internal
- */
 export function deferred(): Deferred {
   let resolve: Function | undefined;
   let reject: Function | undefined;

js/write_file.ts

@@ -3,14 +3,13 @@ import * as msg from "gen/msg_generated";
 import { flatbuffers } from "flatbuffers";
 import * as dispatch from "./dispatch";
 
-/**
+/** Write a new file, with given filename and data synchronously.
- * Write a new file, with given filename and data synchronously.
  *
- *     import { writeFileSync } from "deno";
+ *       import { writeFileSync } from "deno";
  *
- *     const encoder = new TextEncoder("utf-8");
+ *       const encoder = new TextEncoder("utf-8");
- *     const data = encoder.encode("Hello world\n");
+ *       const data = encoder.encode("Hello world\n");
- *     writeFileSync("hello.txt", data);
+ *       writeFileSync("hello.txt", data);
  */
 export function writeFileSync(
   filename: string,
@@ -20,14 +19,13 @@ export function writeFileSync(
   dispatch.sendSync(...req(filename, data, perm));
 }
 
-/**
+/** Write a new file, with given filename and data.
- * Write a new file, with given filename and data.
  *
- *     import { writeFile } from "deno";
+ *       import { writeFile } from "deno";
  *
- *     const encoder = new TextEncoder("utf-8");
+ *       const encoder = new TextEncoder("utf-8");
- *     const data = encoder.encode("Hello world\n");
+ *       const data = encoder.encode("Hello world\n");
- *     await writeFile("hello.txt", data);
+ *       await writeFile("hello.txt", data);
  */
 export async function writeFile(
   filename: string,