Modernize source file headers

cli/asc.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview Definitions for asc.
+ * @license Apache-2.0
+ */
+
 import { OptionDescription } from "./util/options";
 export { OptionDescription };
 

cli/asc.js

@@ -1,15 +1,31 @@
-"use strict";
 /**
- * Compiler frontend for node.js
+ * @license
+ * Copyright 2020 Daniel Wirtz / The AssemblyScript Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview 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
  * directly through ts-node if distribution files are not present (indicated by a `-dev` version).
  *
  * 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 cli/asc
  */
 
 // Use "." instead of "/" as cwd in browsers

cli/transform.d.ts

@@ -1,7 +1,7 @@
 /**
- * Definitions for custom compiler transforms that can be applied with the `--transform` option.
- * @module cli/transform
- *//***/
+ * @fileoverview Compiler transform interface definitions.
+ * @license Apache-2.0
+ */
 
 import { Program, Parser, Module } from "..";
 import { OutputStream } from "./asc";

cli/transform.js

@@ -1,2 +1,7 @@
+/**
+ * @fileoverview Compiler transform interface.
+ * @license Apache-2.0
+ */
+
 // becomes replaced with the actual base by asc
 exports.Transform = function Transform() {};

cli/util/colors.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview Terminal colors utility definitions.
+ * @license Apache-2.0
+ */
+
 interface Colors {
   /** Whether terminal colors are supported. */
   supported: boolean;

cli/util/colors.js

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview Terminal colors utility.
+ * @license Apache-2.0
+ */
+
 var proc = typeof process !== "undefined" && process || {};
 var isCI = proc.env && "CI" in proc.env; // doesn't work when bundled because 'process' is a mock
 

cli/util/find.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview File finding utility definitions.
+ * @license Apache-2.0
+ */
+
 export function files(dirname: string, filter?: ((name: string) => bool) | RegExp): string[];
 export const TS: RegExp;
 export const TS_EXCEPT_DTS: RegExp;

cli/util/find.js

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview File finding utility.
+ * @license Apache-2.0
+ */
+
 const fs = require("fs");
 const path = require("path");
 

cli/util/mkdirp.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview Recursive mkdir definitions.
+ * @license Apache-2.0
+ */
+
 interface Options {
   mode?: number;
 }

cli/util/mkdirp.js

@@ -1,26 +1,28 @@
-/*
-Copyright 2010 James Halliday ([email protected])
-
-This project is free software released under the MIT/X11 license:
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-*/
+/**
+ * @fileoverview Recursive mkdir.
+ * @license
+ * Copyright 2010 James Halliday ([email protected])
+ * 
+ * This project is free software released under the MIT/X11 license:
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 
 var path = require("path");
 var fs = require("fs");

cli/util/options.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview Command line options utility definitions.
+ * @license Apache-2.0
+ */
+
 /** Command line option description. */
 export interface OptionDescription {
   /** Textual description. */

cli/util/options.js

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview Command line options utility.
+ * @license Apache-2.0
+ */
+
 const colorsUtil = require("./colors");
 
 // type | meaning

cli/util/utf8.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview UTF8 utility definitions.
+ * @license Apache-2.0
+ */
+
 /**
  * Calculates the UTF8 byte length of a string.
  * @param {string} string String

cli/util/utf8.js

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview UTF8 utility.
+ * @license Apache-2.0
+ */
+
 // @protobufjs/utf8
 
 /**

scripts/build-diagnostics.js

@@ -2,13 +2,16 @@ var fs = require("fs");
 
 var messages = require(__dirname + "/../src/diagnosticMessages.json");
 
-var sb = [
-  "/**\n",
-  " * Generated from diagnosticsMessages.json. Do not edit.\n",
-  " * @module diagnostics\n",
-  " *//***/\n\n",
-  "/* tslint:disable:max-line-length */\n\n"
-];
+var header = `/**
+ * @fileoverview Generated from diagnosticsMessages.json. Do not edit.
+ * @license Apache-2.0
+ */
+
+/* tslint:disable:max-line-length */
+
+`.replace(/\r\n/g, "\n");
+
+var sb = [ header ];
 
 function makeKey(text) {
   return text.replace(/[^\w]+/g, "_").replace(/_+$/, "");

src/ast.ts

@@ -1,7 +1,18 @@
 /**
- * Abstract syntax tree representing a source file once parsed.
- * @module ast
- *//***/
+ * @fileoverview Abstract syntax tree representing a source file once parsed.
+ *
+ * Each node in the AST is represented by an instance of a subclass of `Node`,
+ * with its `Node#kind` represented by one of the `NodeKind` constants, which
+ * dependent code typically switches over. The intended way to create a node
+ * is to use the respective `Node.createX` method instead of its constructor.
+ *
+ * Note that the AST does not contain any type information except type names.
+ *
+ * @license Apache-2.0
+ */
+
+// TODO: Make the AST more easily serializable by refactoring `Node#range` so
+// it doesn't reference the non-serializable `Source` object.
 
 import {
   CommonFlags,

src/builtins.ts

@@ -1,9 +1,29 @@
 /**
- * Built-in elements providing WebAssembly core functionality.
- * @module builtins
- *//***/
+ * @fileoverview Built-in elements providing core WebAssembly functionality.
+ *
+ * Each builtin is linked to its definition in std/assembly/builtins.ts.
+ * When its prototype is called, the compiler recognizes the `@builtin`
+ * decorator, looks up the respective handler in the global builtins map
+ * and executes it, with the handler directly emitting WebAssembly code
+ * according to context.
+ *
+ * Builtins can be categorized into core builtins that typically are generic
+ * and emit code directly and aliases calling core builtins with overridden
+ * contexts. The latter is used by inline assembler aliases of WebAssembly
+ * instructions, like `i64.load8_u` deferring to `<i64>load<u8>`.
+ *
+ * The `contextIsExact` modifier is used to force a specific instruction
+ * family. A `i32.store8` deferring to `<i32>store<i8>` for example is
+ * ambiguous in that the input can still be an i32 or an i64, leading to
+ * either an `i32.store8` or an `i64.store8`, so `i32` is forced there.
+ * This behavior is indicated by `from i32/i64` in the comments below.
+ *
+ * @license Apache-2.0
+ */
+
+// TODO: Add builtins for `i32.add` etc. that do not have a core builtin.
 
- import {
+import {
   Compiler,
   Constraints,
   RuntimeFeatures
@@ -586,7 +606,7 @@ export class BuiltinContext {
   contextIsExact: bool;
 }
 
-/** Registered builtins. */
+/** Global builtins map. */
 export const builtins = new Map<string,(ctx: BuiltinContext) => ExpressionRef>();
 
 // === Static type evaluation =================================================================

src/common.ts

@@ -1,7 +1,7 @@
 /**
- * Common constants.
- * @module common
- *//***/
+ * @fileoverview Common constants used by various parts of the compiler.
+ * @license Apache-2.0
+ */
 
 /** Indicates traits of a {@link Node} or {@link Element}. */
 export enum CommonFlags {

src/compiler.ts

@@ -1,7 +1,7 @@
 /**
- * The AssemblyScript compiler.
- * @module compiler
- *//***/
+ * @fileoverview The AssemblyScript compiler.
+ * @license Apache-2.0
+ */
 
 import {
   BuiltinNames,

src/definitions.ts

@@ -1,9 +1,13 @@
 /**
- * Definition builders for WebIDL and TypeScript.
- * @module definitions
- *//***/
+ * @fileoverview Builders for various definitions describing a module.
+ *
+ * - TSDBuilder: Creates a TypeScript definition file (.d.ts)
+ * - IDLBuilder: Creates a WebIDL interface definition (.webidl)
+ *
+ * @license Apache-2.0
+ */
 
- import {
+import {
   CommonFlags
 } from "./common";
 

src/diagnosticMessages.generated.ts

@@ -1,7 +1,7 @@
 /**
- * Generated from diagnosticsMessages.json. Do not edit.
- * @module diagnostics
- *//***/
+ * @fileoverview Generated from diagnosticsMessages.json. Do not edit.
+ * @license Apache-2.0
+ */
 
 /* tslint:disable:max-line-length */
 

src/diagnostics.ts

@@ -1,8 +1,7 @@
 /**
- * Shared diagnostic handling inherited by the parser and the compiler.
- * @module diagnostics
- * @preferred
- *//***/
+ * @fileoverview Shared diagnostic handling.
+ * @license Apache-2.0
+ */
 
 import {
   Range

src/extra/ast.ts

@@ -1,10 +1,10 @@
 /**
- * Abstract Syntax Tree extras.
+ * @fileoverview Abstract Syntax Tree extras.
  *
- * Not needed in a standalone compiler but useful for testing the parser.
+ * Provides serialization of the AssemblyScript AST back to it source form.
  *
- * @module extra/ast
- *//***/
+ * @license Apache-2.0
+ */
 
 import {
   Node,