Set up documentation generation

.gitignore

@@ -1,4 +1,5 @@
-node_modules/
 npm-debug.*
+docs/
+node_modules/
 out/
 raw/

bin/asc.js

@@ -1,5 +1,5 @@
 /**
- * @file Compiler frontend for node.js
+ * Compiler frontend for node.js
  *
  * Uses the low-level API exported from src/index.ts so it works with the compiler compiled to
  * JavaScript as well as the compiler compiled to WebAssembly (eventually). Runs the sources
@@ -7,6 +7,8 @@
  *
  * Can also be packaged as a bundle suitable for in-browser use with the standard library injected
  * in the build step. See dist/asc.js for the bundle and webpack.config.js for building details.
+ *
+ * @module asc
  */
 
 const fs = require("fs");

package-lock.json

@@ -10,12 +10,78 @@
       "integrity": "sha512-ONhaKPIufzzrlNbqtWFFd+jlnemX6lJAgq9ZeiZtS7I1PIf/la7CW4m83rTXRnVnsMbW2k56pGYu7AUFJD9Pow==",
       "dev": true
     },
+    "@types/events": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/@types/events/-/events-1.2.0.tgz",
+      "integrity": "sha512-KEIlhXnIutzKwRbQkGWb/I4HFqBuUykAdHgDED6xqwXJfONCjF5VoE0cXEiurh3XauygxzeDzgtXUqvLkxFzzA==",
+      "dev": true
+    },
+    "@types/fs-extra": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/@types/fs-extra/-/fs-extra-5.0.1.tgz",
+      "integrity": "sha512-h3wnflb+jMTipvbbZnClgA2BexrT4w0GcfoCz5qyxd0IRsbqhLSyesM6mqZTAnhbVmhyTm5tuxfRu9R+8l+lGw==",
+      "dev": true,
+      "requires": {
+        "@types/node": "9.4.7"
+      }
+    },
+    "@types/glob": {
+      "version": "5.0.35",
+      "resolved": "https://registry.npmjs.org/@types/glob/-/glob-5.0.35.tgz",
+      "integrity": "sha512-wc+VveszMLyMWFvXLkloixT4n0harUIVZjnpzztaZ0nKLuul7Z32iMt2fUFGAaZ4y1XWjFRMtCI5ewvyh4aIeg==",
+      "dev": true,
+      "requires": {
+        "@types/events": "1.2.0",
+        "@types/minimatch": "3.0.3",
+        "@types/node": "9.4.7"
+      }
+    },
+    "@types/handlebars": {
+      "version": "4.0.36",
+      "resolved": "https://registry.npmjs.org/@types/handlebars/-/handlebars-4.0.36.tgz",
+      "integrity": "sha512-LjNiTX7TY7wtuC6y3QwC93hKMuqYhgV9A1uXBKNvZtVC8ZvyWAjZkJ5BvT0K7RKqORRYRLMrqCxpw5RgS+MdrQ==",
+      "dev": true
+    },
+    "@types/highlight.js": {
+      "version": "9.12.2",
+      "resolved": "https://registry.npmjs.org/@types/highlight.js/-/highlight.js-9.12.2.tgz",
+      "integrity": "sha512-y5x0XD/WXDaGSyiTaTcKS4FurULJtSiYbGTeQd0m2LYZGBcZZ/7fM6t5H/DzeUF+kv8y6UfmF6yJABQsHcp9VQ==",
+      "dev": true
+    },
+    "@types/lodash": {
+      "version": "4.14.104",
+      "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.14.104.tgz",
+      "integrity": "sha512-ufQcVg4daO8xQ5kopxRHanqFdL4AI7ondQkV+2f+7mz3gvp0LkBx2zBRC6hfs3T87mzQFmf5Fck7Fi145Ul6NQ==",
+      "dev": true
+    },
+    "@types/marked": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/@types/marked/-/marked-0.3.0.tgz",
+      "integrity": "sha512-CSf9YWJdX1DkTNu9zcNtdCcn6hkRtB5ILjbhRId4ZOQqx30fXmdecuaXhugQL6eyrhuXtaHJ7PHI+Vm7k9ZJjg==",
+      "dev": true
+    },
+    "@types/minimatch": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@types/minimatch/-/minimatch-3.0.3.tgz",
+      "integrity": "sha512-tHq6qdbT9U1IRSGf14CL0pUlULksvY9OZ+5eEgl1N7t+OA3tGvNpxJCzuKQlsNgCVwbAs670L1vcVQi8j9HjnA==",
+      "dev": true
+    },
     "@types/node": {
       "version": "9.4.7",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-9.4.7.tgz",
       "integrity": "sha512-4Ba90mWNx8ddbafuyGGwjkZMigi+AWfYLSDCpovwsE63ia8w93r3oJ8PIAQc3y8U+XHcnMOHPIzNe3o438Ywcw==",
       "dev": true
     },
+    "@types/shelljs": {
+      "version": "0.7.8",
+      "resolved": "https://registry.npmjs.org/@types/shelljs/-/shelljs-0.7.8.tgz",
+      "integrity": "sha512-M2giRw93PxKS7YjU6GZjtdV9HASdB7TWqizBXe4Ju7AqbKlWvTr0gNO92XH56D/gMxqD/jNHLNfC5hA34yGqrQ==",
+      "dev": true,
+      "requires": {
+        "@types/glob": "5.0.35",
+        "@types/node": "9.4.7"
+      }
+    },
     "acorn": {
       "version": "5.5.3",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-5.5.3.tgz",
@@ -48,6 +114,34 @@
       "integrity": "sha1-rCsnk5xUPpXSwG5/f1wnvkqlQ74=",
       "dev": true
     },
+    "align-text": {
+      "version": "0.1.4",
+      "resolved": "https://registry.npmjs.org/align-text/-/align-text-0.1.4.tgz",
+      "integrity": "sha1-DNkKVhCT810KmSVsIrcGlDP60Rc=",
+      "dev": true,
+      "requires": {
+        "kind-of": "3.2.2",
+        "longest": "1.0.1",
+        "repeat-string": "1.6.1"
+      },
+      "dependencies": {
+        "kind-of": {
+          "version": "3.2.2",
+          "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-3.2.2.tgz",
+          "integrity": "sha1-MeohpzS6ubuw8yRm2JOupR5KPGQ=",
+          "dev": true,
+          "requires": {
+            "is-buffer": "1.1.6"
+          }
+        }
+      }
+    },
+    "amdefine": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/amdefine/-/amdefine-1.0.1.tgz",
+      "integrity": "sha1-SlKCrBZHKek2Gbz9OtFR+BfOkfU=",
+      "dev": true
+    },
     "ansi-escapes": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-3.0.0.tgz",
@@ -1351,6 +1445,26 @@
       "integrity": "sha1-1UVjW+HjPFQmScaRc+Xeas+uNN0=",
       "dev": true
     },
+    "center-align": {
+      "version": "0.1.3",
+      "resolved": "https://registry.npmjs.org/center-align/-/center-align-0.1.3.tgz",
+      "integrity": "sha1-qg0yYptu6XIgBBHL1EYckHvCt60=",
+      "dev": true,
+      "optional": true,
+      "requires": {
+        "align-text": "0.1.4",
+        "lazy-cache": "1.0.4"
+      },
+      "dependencies": {
+        "lazy-cache": {
+          "version": "1.0.4",
+          "resolved": "https://registry.npmjs.org/lazy-cache/-/lazy-cache-1.0.4.tgz",
+          "integrity": "sha1-odePw6UEdMuAhF07O24dpJpEbo4=",
+          "dev": true,
+          "optional": true
+        }
+      }
+    },
     "chalk": {
       "version": "2.3.2",
       "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.3.2.tgz",
@@ -2491,6 +2605,17 @@
         "readable-stream": "2.3.5"
       }
     },
+    "fs-extra": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-5.0.0.tgz",
+      "integrity": "sha512-66Pm4RYbjzdyeuqudYqhFiNBbCIuI9kgRqLPSHIlXHidW8NIQtVdkM1yeZ4lXwuhbTETv3EUGMNHAAw6hiundQ==",
+      "dev": true,
+      "requires": {
+        "graceful-fs": "4.1.11",
+        "jsonfile": "4.0.0",
+        "universalify": "0.1.1"
+      }
+    },
     "fs-write-stream-atomic": {
       "version": "1.0.10",
       "resolved": "https://registry.npmjs.org/fs-write-stream-atomic/-/fs-write-stream-atomic-1.0.10.tgz",
@@ -2787,6 +2912,89 @@
         "lodash": "4.17.5"
       }
     },
+    "handlebars": {
+      "version": "4.0.11",
+      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.0.11.tgz",
+      "integrity": "sha1-Ywo13+ApS8KB7a5v/F0yn8eYLcw=",
+      "dev": true,
+      "requires": {
+        "async": "1.5.2",
+        "optimist": "0.6.1",
+        "source-map": "0.4.4",
+        "uglify-js": "2.8.29"
+      },
+      "dependencies": {
+        "camelcase": {
+          "version": "1.2.1",
+          "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-1.2.1.tgz",
+          "integrity": "sha1-m7UwTS4LVmmLLHWLCKPqqdqlijk=",
+          "dev": true,
+          "optional": true
+        },
+        "cliui": {
+          "version": "2.1.0",
+          "resolved": "https://registry.npmjs.org/cliui/-/cliui-2.1.0.tgz",
+          "integrity": "sha1-S0dXYP+AJkx2LDoXGQMukcf+oNE=",
+          "dev": true,
+          "optional": true,
+          "requires": {
+            "center-align": "0.1.3",
+            "right-align": "0.1.3",
+            "wordwrap": "0.0.2"
+          }
+        },
+        "source-map": {
+          "version": "0.4.4",
+          "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.4.4.tgz",
+          "integrity": "sha1-66T12pwNyZneaAMti092FzZSA2s=",
+          "dev": true,
+          "requires": {
+            "amdefine": "1.0.1"
+          }
+        },
+        "uglify-js": {
+          "version": "2.8.29",
+          "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-2.8.29.tgz",
+          "integrity": "sha1-KcVzMUgFe7Th913zW3qcty5qWd0=",
+          "dev": true,
+          "optional": true,
+          "requires": {
+            "source-map": "0.5.7",
+            "uglify-to-browserify": "1.0.2",
+            "yargs": "3.10.0"
+          },
+          "dependencies": {
+            "source-map": {
+              "version": "0.5.7",
+              "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.5.7.tgz",
+              "integrity": "sha1-igOdLRAh0i0eoUyA2OpGi6LvP8w=",
+              "dev": true,
+              "optional": true
+            }
+          }
+        },
+        "wordwrap": {
+          "version": "0.0.2",
+          "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-0.0.2.tgz",
+          "integrity": "sha1-t5Zpu0LstAn4PVg8rVLKF+qhZD8=",
+          "dev": true,
+          "optional": true
+        },
+        "yargs": {
+          "version": "3.10.0",
+          "resolved": "https://registry.npmjs.org/yargs/-/yargs-3.10.0.tgz",
+          "integrity": "sha1-9+572FfdfB0tOMDnTvvWgdFDH9E=",
+          "dev": true,
+          "optional": true,
+          "requires": {
+            "camelcase": "1.2.1",
+            "cliui": "2.1.0",
+            "decamelize": "1.2.0",
+            "window-size": "0.1.0"
+          }
+        }
+      }
+    },
     "has-ansi": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/has-ansi/-/has-ansi-2.0.0.tgz",
@@ -2873,6 +3081,12 @@
         "minimalistic-assert": "1.0.0"
       }
     },
+    "highlight.js": {
+      "version": "9.12.0",
+      "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-9.12.0.tgz",
+      "integrity": "sha1-5tnb5Xy+/mB1HwKvM2GVhwyQwB4=",
+      "dev": true
+    },
     "hmac-drbg": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/hmac-drbg/-/hmac-drbg-1.0.1.tgz",
@@ -3484,6 +3698,15 @@
       "integrity": "sha1-Hq3nrMASA0rYTiOWdn6tn6VJWCE=",
       "dev": true
     },
+    "jsonfile": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz",
+      "integrity": "sha1-h3Gq4HmbZAdrdmQPygWPnBDjPss=",
+      "dev": true,
+      "requires": {
+        "graceful-fs": "4.1.11"
+      }
+    },
     "keyv": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/keyv/-/keyv-3.0.0.tgz",
@@ -3846,6 +4069,12 @@
       "resolved": "https://registry.npmjs.org/long/-/long-4.0.0.tgz",
       "integrity": "sha512-XsP+KhQif4bjX1kbuSiySJFNAehNxgLb6hPRGJ9QsUr8ajHkuXGdrHmFUTUUXhDwVX2R5bY4JNZEwbUiMhV+MA=="
     },
+    "longest": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/longest/-/longest-1.0.1.tgz",
+      "integrity": "sha1-MKCy2jj3N3DoKUoNIuZiXtd9AJc=",
+      "dev": true
+    },
     "loose-envify": {
       "version": "1.3.1",
       "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.3.1.tgz",
@@ -3900,6 +4129,12 @@
         "object-visit": "1.0.1"
       }
     },
+    "marked": {
+      "version": "0.3.17",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-0.3.17.tgz",
+      "integrity": "sha512-+AKbNsjZl6jFfLPwHhWmGTqE009wTKn3RTmn9K8oUKHrX/abPJjtcRtXpYB/FFrwPJRUA86LX/de3T0knkPCmQ==",
+      "dev": true
+    },
     "md5.js": {
       "version": "1.3.4",
       "resolved": "https://registry.npmjs.org/md5.js/-/md5.js-1.3.4.tgz",
@@ -4434,6 +4669,24 @@
         "mimic-fn": "1.2.0"
       }
     },
+    "optimist": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/optimist/-/optimist-0.6.1.tgz",
+      "integrity": "sha1-2j6nRob6IaGaERwybpDrFaAZZoY=",
+      "dev": true,
+      "requires": {
+        "minimist": "0.0.10",
+        "wordwrap": "0.0.3"
+      },
+      "dependencies": {
+        "minimist": {
+          "version": "0.0.10",
+          "resolved": "https://registry.npmjs.org/minimist/-/minimist-0.0.10.tgz",
+          "integrity": "sha1-3j+YVD2/lggr5IrRoMfNqDYwHc8=",
+          "dev": true
+        }
+      }
+    },
     "ora": {
       "version": "0.2.3",
       "resolved": "https://registry.npmjs.org/ora/-/ora-0.2.3.tgz",
@@ -4821,6 +5074,12 @@
       "integrity": "sha512-MtEC1TqN0EU5nephaJ4rAtThHtC86dNN9qCuEhtshvpVBkAW5ZO7BASN9REnF9eoXGcRub+pFuKEpOHE+HbEMw==",
       "dev": true
     },
+    "progress": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/progress/-/progress-2.0.0.tgz",
+      "integrity": "sha1-ihvjZr+Pwj2yvSPxDG/pILQ4nR8=",
+      "dev": true
+    },
     "promise-inflight": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/promise-inflight/-/promise-inflight-1.0.1.tgz",
@@ -5207,6 +5466,16 @@
       "integrity": "sha512-TTlYpa+OL+vMMNG24xSlQGEJ3B/RzEfUlLct7b5G/ytav+wPrplCpVMFuwzXbkecJrb6IYo1iFb0S9v37754mg==",
       "dev": true
     },
+    "right-align": {
+      "version": "0.1.3",
+      "resolved": "https://registry.npmjs.org/right-align/-/right-align-0.1.3.tgz",
+      "integrity": "sha1-YTObci/mo1FWiSENJOFMlhSGE+8=",
+      "dev": true,
+      "optional": true,
+      "requires": {
+        "align-text": "0.1.4"
+      }
+    },
     "rimraf": {
       "version": "2.6.2",
       "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.6.2.tgz",
@@ -6100,6 +6369,43 @@
       "integrity": "sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=",
       "dev": true
     },
+    "typedoc": {
+      "version": "0.11.1",
+      "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.11.1.tgz",
+      "integrity": "sha512-jdNIoHm5wkZqxQTe/g9AQ3LKnZyrzHXqu6A/c9GUOeJyBWLxNr7/Dm3rwFvLksuxRNwTvY/0HRDU9sJTa9WQSg==",
+      "dev": true,
+      "requires": {
+        "@types/fs-extra": "5.0.1",
+        "@types/handlebars": "4.0.36",
+        "@types/highlight.js": "9.12.2",
+        "@types/lodash": "4.14.104",
+        "@types/marked": "0.3.0",
+        "@types/minimatch": "3.0.3",
+        "@types/shelljs": "0.7.8",
+        "fs-extra": "5.0.0",
+        "handlebars": "4.0.11",
+        "highlight.js": "9.12.0",
+        "lodash": "4.17.5",
+        "marked": "0.3.17",
+        "minimatch": "3.0.4",
+        "progress": "2.0.0",
+        "shelljs": "0.8.1",
+        "typedoc-default-themes": "0.5.0",
+        "typescript": "2.7.2"
+      }
+    },
+    "typedoc-default-themes": {
+      "version": "0.5.0",
+      "resolved": "https://registry.npmjs.org/typedoc-default-themes/-/typedoc-default-themes-0.5.0.tgz",
+      "integrity": "sha1-bcJDPnjti+qOiHo6zeLzF4W9Yic=",
+      "dev": true
+    },
+    "typedoc-plugin-external-module-name": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/typedoc-plugin-external-module-name/-/typedoc-plugin-external-module-name-1.1.1.tgz",
+      "integrity": "sha512-Erc0MyKDGYIN7kSlIjgifVieZEogg8YwOH8bjW6RXb0y44hVeTER0UoW6Rh+n8leg6rvlPdnH092aFfcd8kRlA==",
+      "dev": true
+    },
     "typescript": {
       "version": "2.7.2",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-2.7.2.tgz",
@@ -6124,6 +6430,13 @@
         }
       }
     },
+    "uglify-to-browserify": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/uglify-to-browserify/-/uglify-to-browserify-1.0.2.tgz",
+      "integrity": "sha1-bgkk1r2mta/jSeOabWMoUKD4grc=",
+      "dev": true,
+      "optional": true
+    },
     "uglifyjs-webpack-plugin": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/uglifyjs-webpack-plugin/-/uglifyjs-webpack-plugin-1.2.3.tgz",
@@ -6207,6 +6520,12 @@
         "imurmurhash": "0.1.4"
       }
     },
+    "universalify": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.1.tgz",
+      "integrity": "sha1-+nG63UQ3r0wUiEHjs7Fl+enlkLc=",
+      "dev": true
+    },
     "unset-value": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/unset-value/-/unset-value-1.0.0.tgz",
@@ -6716,6 +7035,19 @@
       "integrity": "sha1-2e8H3Od7mQK4o6j6SzHD4/fm6Ho=",
       "dev": true
     },
+    "window-size": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/window-size/-/window-size-0.1.0.tgz",
+      "integrity": "sha1-VDjNLqk7IC76Ohn+iIeu58lPnJ0=",
+      "dev": true,
+      "optional": true
+    },
+    "wordwrap": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-0.0.3.tgz",
+      "integrity": "sha1-o9XabNXAvAAI03I0u68b7WMFkQc=",
+      "dev": true
+    },
     "worker-farm": {
       "version": "1.6.0",
       "resolved": "https://registry.npmjs.org/worker-farm/-/worker-farm-1.6.0.tgz",

package.json

@@ -25,6 +25,8 @@
     "source-map-support": "^0.5.3",
     "ts-loader": "^4.0.1",
     "tslint": "^5.9.1",
+    "typedoc": "^0.11.1",
+    "typedoc-plugin-external-module-name": "^1.1.1",
     "typescript": "^2.7.2",
     "webpack": "^4.1.1",
     "webpack-cli": "^2.0.11"
@@ -48,7 +50,8 @@
     "test:compiler": "node tests/compiler",
     "test": "npm run test:config --scripts-prepend-node-path && npm run test:parser --scripts-prepend-node-path && npm run test:compiler --scripts-prepend-node-path",
     "test:pr": "npm run clean && npm test && npm run build && npm test && npm run clean",
-    "all": "npm run lint && npm run clean && npm test && npm run build && npm test"
+    "all": "npm run lint && npm run clean && npm test && npm run build && npm test",
+    "docs": "typedoc --tsconfig tsconfig-docs.json --mode modules --name \"AssemblyScript Compiler API\" --out ./docs/api --ignoreCompilerErrors --excludeNotExported --excludePrivate --excludeExternals --exclude **/std/** --includeDeclarations --readme src/README.md"
   },
   "files": [
     "bin/",

scripts/build-diagnostics.js

@@ -3,7 +3,10 @@ var fs = require("fs");
 var messages = require(__dirname + "/../src/diagnosticMessages.json");
 
 var sb = [
-  "// code below is generated from diagnosticsMessages.json by scripts/build-diagnostics\n",
+  "/**\n",
+  " * Generated from diagnosticsMessages.json. Do not edit.\n",
+  " * @module diagnostics\n",
+  " *//***/\n\n",
   "/* tslint:disable:max-line-length */\n\n"
 ];
 
@@ -11,6 +14,7 @@ function makeKey(text) {
   return text.replace(/[^\w]+/g, "_").replace(/_+$/, "");
 }
 
+sb.push("/** Enum of available diagnostic codes. */\n");
 sb.push("export enum DiagnosticCode {\n");
 
 var first = true;
@@ -24,7 +28,9 @@ Object.keys(messages).forEach(text => {
   sb.push("  " + key + " = " + messages[text]);
 });
 
-sb.push("\n}\n\nexport function diagnosticCodeToString(code: DiagnosticCode): string {\n  switch (code) {\n");
+sb.push("\n}\n\n");
+sb.push("/** Translates a diagnostic code to its respective string. */\n");
+sb.push("export function diagnosticCodeToString(code: DiagnosticCode): string {\n  switch (code) {\n");
 
 Object.keys(messages).forEach(text => {
   sb.push("    case " + messages[text] + ": return " + JSON.stringify(text) + ";\n");

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,
+  normalizePath,
-  resolve as resolvePath
+  resolvePath
-} from "./util/path";
+} 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
+  CharCode,
-} from "../util/charcode";
-
-import {
   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.
+ * TypeScript definitions for Binaryen's C-API.
- * @see https://github.com/WebAssembly/binaryen/blob/master/src/binaryen-c.h
+ *
- */
+ * 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 @@
-/**
+/** @module glue/js *//***/
- * @file Definitions for linking Binaryen with AssemblyScript.
- */
 
 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 @@
-/**
+/** @module glue/js *//***/
- * @file I64 definitions for JavaScript.
- */
 
 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 @@
-/**
+/** @module glue/js *//***/
- * @file Definitions for running JavaScript under node.js.
- */
 
 declare const global: any;
 declare function require(name: string): any;

src/glue/wasm/i64.ts

@@ -1,6 +1,4 @@
-/**
+/** @module glue/wasm *//***/
- * @file I64 wrapper for WebAssembly.
- */
 
 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
+  normalizePath
-} from "./util/path";
+} 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 @@
-/**
+/** @module util *//***/
- * @file Character code utility.
- */
 
 /** 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 @@
-/**
+/** @module util *//***/
- * @file Minimalistic path utility for normalizing and resolving relative paths.
- */
 
 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 @@
-/**
+/** @module util *//***/
- * @file Common text utilities.
- */
 
 const indentX1 = "  ";
 const indentX2 = "    ";

std/assembly.d.ts

@@ -1,6 +1,7 @@
 /**
- * @file Environment definitions for compiling AssemblyScript to WebAssembly using asc.
+ * Environment definitions for compiling AssemblyScript to WebAssembly using asc.
- */
+ * @module std/assembly
+ *//***/
 
 // Types
 

std/assembly/allocator/arena.ts

@@ -1,9 +1,11 @@
 /**
- * @file Arena Memory Allocator
+ * Arena Memory Allocator
  *
  * Provides a `reset_memory` function to reset the heap to its initial state. A user has to make
  * sure that there are no more references to cleared memory afterwards. Always aligns to 8 bytes.
- */
+ *
+ * @module std/assembly/allocator/arena
+ *//***/
 
 import { MASK as AL_MASK } from "./common/alignment";
 

std/assembly/allocator/buddy.ts

@@ -1,6 +1,7 @@
 /**
- * @file Buddy Memory Allocator
+ * Buddy Memory Allocator.
- */
+ * @module stdd/assembly/allocator/buddy
+ *//***/
 
 /*
   Copyright 2018 Evan Wallace

std/assembly/allocator/common/alignment.ts

@@ -1,3 +1,8 @@
+/**
+ * Shared alignment constants.
+ * @module std/assembly/allocator/common/alignment
+ *//***/
+
 /** Number of alignment bits. */
 export const BITS: u32 = 3;
 

std/assembly/allocator/emscripten.ts

@@ -1,10 +1,12 @@
 /**
- * @file Emscripten Memory Allocator
+ * Emscripten Memory Allocator.
  *
  * Uses Emscripten's exported _malloc and _free implementations, i.e., when linking with
  * Emscripten-compiled programs that already provide these. Differs from 'system' in that their
  * names are prefixed with an underscore.
- */
+ *
+ * @module std/assembly/allocator/emscripten
+ *//***/
 
 declare function _malloc(size: usize): usize;
 declare function _free(ptr: usize): void;

std/assembly/allocator/system.ts

@@ -1,9 +1,11 @@
 /**
- * @file System Memory Allocator
+ * System Memory Allocator.
  *
  * Uses the environment's malloc and free implementations, i.e., when linking with other C-like
  * programs that already provide these.
- */
+ *
+ * @module std/assembly/allocator/system
+ *//***/
 
 declare function malloc(size: usize): usize;
 declare function free(ptr: usize): void;

std/assembly/allocator/tlsf.ts

@@ -1,9 +1,11 @@
 /**
- * @file Two-Level Segregate Fit Memory Allocator
+ * Two-Level Segregate Fit Memory Allocator.
  *
  * A general purpose dynamic memory allocator specifically designed to meet real-time requirements.
  * Always aligns to 8 bytes.
- */
+ *
+ * @module std/assembly/allocator/tlsf
+ *//***/
 
 // ╒══════════════ Block size interpretation (32-bit) ═════════════╕
 //    3                   2                   1

std/portable.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file Environment definitions for compiling AssemblyScript to JavaScript using tsc.
+ * Environment definitions for compiling AssemblyScript to JavaScript using tsc.
  *
  * Note that semantic differences require additional explicit conversions for full compatibility.
  * For example, when casting an i32 to an u8, doing `<u8>(someI32 & 0xff)` will yield the same
@@ -7,8 +7,10 @@
  *
  * Note that i64's are not portable (JS numbers are IEEE754 doubles with a maximum safe integer
  * value of 2^53-1) and instead require a compatibility layer to work in JS as well, as for example
- * {@link ./glue/js/i64.d.ts} / {@link ./glue/js/i64.js}.
+ * {@link glue/js/i64} respectively {@link glue/wasm/i64}.
- */
+ *
+ * @module std/portable
+ *//***/
 
 // Portable types
 

std/portable.js

@@ -1,6 +1,4 @@
-/**
+/** @module std/portable *//***/
- * @file Environment implementation for compiling AssemblyScript to JavaScript using tsc.
- */
 
 var globalScope = typeof window !== "undefined" && window || typeof global !== "undefined" && global || self;
 
@@ -168,3 +166,5 @@ globalScope["isString"] = function isString(arg) {
 };
 
 globalScope["isArray"] = Array.isArray;
+
+require("./portable/memory");

std/portable.json

@@ -14,7 +14,6 @@
   },
   "files": [
     "./portable.d.ts",
-    "./portable.js",
+    "./portable.js"
-    "./portable/memory.js"
   ]
 }

tsconfig-docs.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./src/tsconfig.json",
+  "include": [
+    "./src/**/*.ts"
+  ],
+  "exclude": [
+    "./std/**"
+  ]
+}