Set up documentation generation

src/ast.ts

@@ -1,6 +1,7 @@
 /**
- * @file Abstract syntax tree representing a source file once parsed.
- */
+ * Abstract syntax tree representing a source file once parsed.
+ * @module ast
+ *//***/
 
 import {
   CommonFlags,
@@ -16,9 +17,9 @@ import {
 } from "./tokenizer";
 
 import {
-  normalize as normalizePath,
-  resolve as resolvePath
-} from "./util/path";
+  normalizePath,
+  resolvePath
+} from "./util";
 
 export { Token, Range };
 

src/builtins.ts

@@ -1,6 +1,7 @@
 /**
- * @file Built-in elements providing otherwise hard-to-implement functionality.
- */
+ * Built-in elements providing WebAssembly core functionality.
+ * @module builtins
+ *//***/
 
 import {
   Compiler,

src/compiler.ts

@@ -1,6 +1,7 @@
 /**
- * @file The AssemblyScript compiler.
- */
+ * The AssemblyScript compiler.
+ * @module compiler
+ *//***/
 
 import {
   compileCall as compileBuiltinCall,
@@ -300,7 +301,9 @@ export class Compiler extends DiagnosticEmitter {
       let pages = i64_shr_u(i64_align(memoryOffset, 0x10000), i64_new(16, 0));
       module.setMemory(
         i64_low(pages),
-        Module.MAX_MEMORY_WASM32, // TODO: not WASM64 compatible yet
+        this.options.isWasm64
+          ? Module.MAX_MEMORY_WASM64
+          : Module.MAX_MEMORY_WASM32,
         this.memorySegments,
         options.target,
         "memory"

src/decompiler.ts

@@ -1,6 +1,7 @@
 /**
- * @file A decompiler that generates low-level AssemblyScript from WebAssembly binaries.
- */
+ * A decompiler that generates low-level AssemblyScript from WebAssembly binaries.
+ * @module decompiler
+ *//***/
 
 import {
   Module,

src/definitions.ts

@@ -1,6 +1,7 @@
 /**
- * @file Definition builders for WebIDL and TypeScript.
- */
+ * Definition builders for WebIDL and TypeScript.
+ * @module definitions
+ *//***/
 
 import {
   Program,
@@ -26,7 +27,7 @@ import {
 
 import {
   indent
-} from "./util/text";
+} from "./util";
 
 /** Walker base class. */
 abstract class ExportsWalker {

src/diagnosticMessages.generated.ts

@@ -1,6 +1,11 @@
-// code below is generated from diagnosticsMessages.json by scripts/build-diagnostics
+/**
+ * Generated from diagnosticsMessages.json. Do not edit.
+ * @module diagnostics
+ *//***/
+
 /* tslint:disable:max-line-length */
 
+/** Enum of available diagnostic codes. */
 export enum DiagnosticCode {
   Operation_not_supported = 100,
   Operation_is_unsafe = 101,
@@ -100,6 +105,7 @@ export enum DiagnosticCode {
   File_0_not_found = 6054
 }
 
+/** Translates a diagnostic code to its respective string. */
 export function diagnosticCodeToString(code: DiagnosticCode): string {
   switch (code) {
     case 100: return "Operation not supported.";

src/diagnostics.ts

@@ -1,6 +1,8 @@
 /**
- * @file Shared diagnostic handling inherited by the parser and the compiler.
- */
+ * Shared diagnostic handling inherited by the parser and the compiler.
+ * @module diagnostics
+ * @preferred
+ *//***/
 
 import {
   Range
@@ -13,7 +15,7 @@ import {
 
 import {
   isLineBreak
-} from "./util/charcode";
+} from "./util";
 
 export {
   DiagnosticCode,

src/extra/ast.ts

@@ -1,8 +1,10 @@
 /**
- * @file Abstract Syntax Tree extras.
+ * Abstract Syntax Tree extras.
  *
  * Not needed in a standalone compiler but useful for testing the parser.
- */
+ *
+ * @module extra/ast
+ *//***/
 
 import {
   Node,
@@ -82,12 +84,9 @@ import {
 } from "../tokenizer";
 
 import {
-  CharCode
-} from "../util/charcode";
-
-import {
+  CharCode,
   indent
-} from "../util/text";
+} from "../util";
 
 import {
   CommonFlags

src/glue/binaryen.d.ts

@@ -1,7 +1,10 @@
 /**
- * @file TypeScript definitions for Binaryen's C-API.
- * @see https://github.com/WebAssembly/binaryen/blob/master/src/binaryen-c.h
- */
+ * TypeScript definitions for Binaryen's C-API.
+ *
+ * See: https://github.com/WebAssembly/binaryen/blob/master/src/binaryen-c.h
+ *
+ * @module glue/binaryen
+ *//***/
 
 declare function _malloc(size: usize): usize;
 declare function _free(ptr: usize): void;

src/glue/js/binaryen.d.ts

@@ -1,6 +1,4 @@
-/**
- * @file Definitions for linking Binaryen with AssemblyScript.
- */
+/** @module glue/js *//***/
 
 declare function allocate_memory(size: usize): usize;
 declare function free_memory(ptr: usize): void;

src/glue/js/binaryen.js

@@ -1,7 +1,3 @@
-/**
- * @file Glue code for linking Binaryen with AssemblyScript.
- */
-
 // Copy Binaryen exports to global scope
 
 const binaryen = global.Binaryen || require("binaryen");

src/glue/js/i64.d.ts

@@ -1,6 +1,4 @@
-/**
- * @file I64 definitions for JavaScript.
- */
+/** @module glue/js *//***/
 
 declare type I64 = { __Long__: true }; // opaque
 

src/glue/js/i64.js

@@ -1,8 +1,3 @@
-/**
- * @file I64 implementation for JavaScript using long.js.
- * @see https://github.com/dcodeIO/long.js
- */
-
 const Long = global.Long || require("long");
 
 global.i64_new = function(lo, hi) {

src/glue/js/index.ts

@@ -1,6 +1,8 @@
 /**
- * @file JavaScript glue code.
- */
+ * JavaScript glue code.
+ * @module glue/js
+ * @preferred
+ *//***/
 
 import "../../../std/portable";
 import "./binaryen";

src/glue/js/node.d.ts

@@ -1,6 +1,4 @@
-/**
- * @file Definitions for running JavaScript under node.js.
- */
+/** @module glue/js *//***/
 
 declare const global: any;
 declare function require(name: string): any;

src/glue/wasm/i64.ts

@@ -1,6 +1,4 @@
-/**
- * @file I64 wrapper for WebAssembly.
- */
+/** @module glue/wasm *//***/
 
 type I64 = i64;
 
@@ -151,7 +149,7 @@ function i64_to_f64(value: I64): f64 {
   return <f64>value;
 }
 
-import { CharCode } from "../../util/charcode";
+import { CharCode } from "../../util";
 
 @global
 function i64_to_string(value: I64): string {

src/glue/wasm/index.ts

@@ -1,5 +1,7 @@
 /**
- * @file WebAssembly glue code.
- */
+ * WebAssembly glue code.
+ * @module glue/wasm
+ * @preferred
+ *//***/
 
 import "./i64";

src/index.ts

@@ -1,6 +1,7 @@
 /**
- * @file Low-level C-like compiler API.
- */
+ * Low-level C-like compiler API.
+ * @module index
+ *//***/
 
 import {
   Compiler,

src/module.ts

@@ -1,6 +1,7 @@
 /**
- * @file A thin wrapper around Binaryen's C-API.
- */
+ * A thin wrapper around Binaryen's C-API.
+ * @module module
+ *//***/
 
 import {
   Target
@@ -240,8 +241,11 @@ export class Module {
   ref: ModuleRef;
   out: usize;
 
+  /** Maximum number of pages when targeting WASM32. */
   static readonly MAX_MEMORY_WASM32: Index = 0xffff;
-  // TODO: static readonly MAX_MEMORY_WASM64
+
+  /** Maximum number of pages when targeting WASM64. */
+  static readonly MAX_MEMORY_WASM64: Index = 0xffff; // TODO
 
   static create(): Module {
     var module = new Module();
@@ -900,7 +904,7 @@ export class Module {
     _BinaryenModuleInterpret(this.ref);
   }
 
-  toBinary(sourceMapUrl: string | null): Binary {
+  toBinary(sourceMapUrl: string | null): BinaryModule {
     var out = this.out;
     var cStr = allocString(sourceMapUrl);
     var binaryPtr: usize = 0;
@@ -910,7 +914,7 @@ export class Module {
       binaryPtr = readInt(out);
       let binaryBytes = readInt(out + 4);
       sourceMapPtr = readInt(out + 4 * 2);
-      let ret = new Binary();
+      let ret = new BinaryModule();
       ret.output = readBuffer(binaryPtr, binaryBytes);
       ret.sourceMap = readString(sourceMapPtr);
       return ret;
@@ -1191,7 +1195,7 @@ function allocString(str: string | null): usize {
   return ptr;
 }
 
-export function readInt(ptr: usize): i32 {
+function readInt(ptr: usize): i32 {
   return (
      load<u8>(ptr    )        |
     (load<u8>(ptr + 1) <<  8) |
@@ -1200,7 +1204,7 @@ export function readInt(ptr: usize): i32 {
   );
 }
 
-export function readBuffer(ptr: usize, length: usize): Uint8Array {
+function readBuffer(ptr: usize, length: usize): Uint8Array {
   var ret = new Uint8Array(length);
   for (let i: usize = 0; i < length; ++i) {
     ret[i] = load<u8>(ptr + i);
@@ -1254,7 +1258,7 @@ export function readString(ptr: usize): string | null {
 }
 
 /** Result structure of {@link Module#toBinary}. */
-class Binary {
+export class BinaryModule {
   /** WebAssembly binary. */
   output: Uint8Array;
   /** Source map, if generated. */

src/parser.ts

@@ -1,6 +1,7 @@
 /**
- * @file A TypeScript parser for the AssemblyScript subset.
- */
+ * A TypeScript parser for the AssemblyScript subset.
+ * @module parser
+ *//***/
 
 import {
   Program,
@@ -22,8 +23,8 @@ import {
 } from "./diagnostics";
 
 import {
-  normalize as normalizePath
-} from "./util/path";
+  normalizePath
+} from "./util";
 
 import {
 
@@ -34,7 +35,6 @@ import {
   CommonTypeNode,
   TypeNode,
   SignatureNode,
-  CommentKind,
 
   Expression,
   AssertionKind,

src/program.ts

@@ -1,6 +1,7 @@
 /**
- * @file AssemblyScript's intermediate representation describing a program's elements.
- */
+ * AssemblyScript's intermediate representation describing a program's elements.
+ * @module program
+ *//***/
 
 import {
   Options

src/tokenizer.ts

@@ -1,9 +1,11 @@
 /**
- * @file A TypeScript tokenizer modified for AssemblyScript.
+ * A TypeScript tokenizer modified for AssemblyScript.
  *
  * Skips over trivia and provides a general mark/reset mechanism for the parser to utilize on
  * ambiguous tokens.
- */
+ *
+ * @module tokenizer
+ *//***/
 
 import {
   DiagnosticCode,
@@ -25,7 +27,7 @@ import {
   isDecimalDigit,
   isOctalDigit,
   isKeywordCharacter
-} from "./util/charcode";
+} from "./util";
 
 /** Named token types. */
 export enum Token {

src/types.ts

@@ -1,6 +1,7 @@
 /**
- * @file Mappings from AssemblyScript types to WebAssembly types.
- */
+ * Mappings from AssemblyScript types to WebAssembly types.
+ * @module types
+ *//***/
 
 import {
   Class,
@@ -17,25 +18,43 @@ import {
 export const enum TypeKind {
 
   // signed integers
+
+  /** An 8-bit signed integer. */
   I8,
+  /** A 16-bit signed integer. */
   I16,
+  /** A 32-bit signed integer. */
   I32,
+  /** A 64-bit signed integer. */
   I64,
+  /** A 32-bit/64-bit signed integer, depending on the target. */
   ISIZE,
 
   // unsigned integers
+
+  /** An 8-bit unsigned integer. */
   U8,
+  /** A 16-bit unsigned integer. */
   U16,
+  /** A 32-bit unsigned integer. Also the base of function types. */
   U32,
+  /** A 64-bit unsigned integer. */
   U64,
+  /** A 32-bit/64-bit unsigned integer, depending on the target. Also the base of class types. */
   USIZE,
+  /** A 1-bit unsigned integer. */
   BOOL, // sic
 
   // floats
+
+  /** A 32-bit float. */
   F32,
+  /** A 64-bit double. */
   F64,
 
   // other
+
+  /** No return type. */
   VOID
 }
 
@@ -451,7 +470,7 @@ export class Signature {
   parameterTypes: Type[];
   /** Parameter names, if known, excluding `this`. */
   parameterNames: string[] | null;
-  /** Number of required parameters. Other parameters are considered optional. */
+  /** Number of required parameters excluding `this`. Other parameters are considered optional. */
   requiredParameters: i32;
   /** Return type. */
   returnType: Type;
@@ -462,6 +481,7 @@ export class Signature {
   /** Cached {@link FunctionTarget}. */
   cachedFunctionTarget: FunctionTarget | null = null;
 
+  /** Constructs a new signature. */
   constructor(
     parameterTypes: Type[] | null = null,
     returnType: Type | null = null,

src/util/charcode.ts

@@ -1,6 +1,4 @@
-/**
- * @file Character code utility.
- */
+/** @module util *//***/
 
 /** An enum of named character codes. */
 export const enum CharCode {

src/util/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Various compiler utilities.
+ * @module util
+ * @preferred
+ *//***/
+
+export * from "./charcode";
+export * from "./path";
+export * from "./text";

src/util/path.ts

@@ -1,6 +1,4 @@
-/**
- * @file Minimalistic path utility for normalizing and resolving relative paths.
- */
+/** @module util *//***/
 
 import {
   CharCode
@@ -12,7 +10,7 @@ const separator = CharCode.SLASH;
  * Normalizes the specified path, removing interior placeholders.
  * Expects a posix-compatible relative path (not Windows compatible).
  */
-export function normalize(path: string): string {
+export function normalizePath(path: string): string {
   var pos = 0;
   var len = path.length;
 
@@ -96,11 +94,11 @@ export function normalize(path: string): string {
 }
 
 /** Resolves the specified path relative to the specified origin. */
-export function resolve(normalizedPath: string, origin: string): string {
+export function resolvePath(normalizedPath: string, origin: string): string {
   if (normalizedPath.startsWith("std/")) {
     return normalizedPath;
   }
-  return normalize(
+  return normalizePath(
     dirname(origin) + String.fromCharCode(separator) + normalizedPath
   );
 }

src/util/text.ts

@@ -1,6 +1,4 @@
-/**
- * @file Common text utilities.
- */
+/** @module util *//***/
 
 const indentX1 = "  ";
 const indentX2 = "    ";