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:https://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:https://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 `containingFile`
+ /** Resolve the `fileName` for a given `moduleSpecifier` and
+ * `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 absolute
- * identifiers for dependent modules that are required by this module.
+ /** For a given module specifier and containing file, return a list of
+ * absolute identifiers for dependent modules that are required by this
+ * 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";
- * copyFileSync("from.txt", "to.txt");
+ *  import { copyFileSync } from "deno";
+ *  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";
- * await copyFile("from.txt", "to.txt");
+ *  import { copyFile } from "deno";
+ *  await copyFile("from.txt", "to.txt");
  */
 export async function copyFile(from: string, to: string): Promise<void> {
  await dispatch.sendAsync(...req(from, to));