v5.6.20

This reverts commit 420492388b.

.babelrc

@@ -2,5 +2,6 @@
   "stage": 0,
   "loose": ["all"],
   "blacklist": ["es6.tailCall"],
-  "optional": ["optimisation.flow.forOf"]
+  "optional": ["optimisation.flow.forOf"],
+  "plugins": ["./tools/build-plugins/protect"]
 }

.eslintrc

@@ -18,7 +18,8 @@
     "new-cap": 0,
     "no-loop-func": 0,
     "no-unreachable": 0,
-    "no-labels": 0
+    "no-labels": 0,
+    "no-process-exit": 0
   },
   "env": {
     "node": true

.gitignore

@@ -15,3 +15,4 @@ test/core/tmp
 /packages/babel-runtime/helpers/*.js
 /packages/babel-runtime/regenerator/*.js
 /lib
+_babel.github.io

.npmignore

@@ -13,3 +13,4 @@
 /vendor
 /packages
 /src
+_babel.github.io

.travis.yml

@@ -1,14 +1,35 @@
-#sudo: false
 language: node_js
 cache:
   directories:
-    - node_modules
+  - node_modules
 node_js:
-  - "0.12"
-  - "iojs"
+- "0.10"
+- "0.12"
+- iojs
 
-before_script: "npm install -g codeclimate-test-reporter"
-script: "make test-travis"
+before_script: ./tools/setup-git.sh
+script: make test-travis
+after_success: ./tools/merge-development-with-master.sh
 
 notifications:
   slack: babeljs:5Wy4QX13KVkGy9CnU0rmvgeK
+
+before_deploy:
+- make prepublish
+
+deploy:
+  provider: npm
+  email: sebmck@gmail.com
+  skip_cleanup: true
+  api_key:
+    secure: Q/pZStwherdYPCqCa0aUuiEktLcx6ccBxieyH8j9IXdDgty0ydmnajZfUnlZuCjN13XI9esM44nSJFTWZvntTryDQAQm37c63VXhAEnw/qrAINI06yt0gLBTT69/fKvIAkH8l48nmW32ZS2dse3rHRPZF1CwyQLC/pdMip8I4sM=
+  on:
+    branch: master
+    tags: true
+    repo: babel/babel
+
+after_deploy:
+- make publish-cli
+- make publish-runtime
+- make build-website
+- make comment-issues

CHANGELOG.md

@@ -9,10 +9,83 @@
 > - [Internal]
 > - [Polish]
 
-_Note: Gaps between patch versions are faulty/broken releases._
+_Note: Gaps between patch versions are faulty, broken or test releases._
 
 See [CHANGELOG - 6to5](CHANGELOG-6to5.md) for the pre-4.0.0 version changelog.
 
+## 5.6.17
+
+ * **Bug Fix**
+  * Fix `CodeGenerator.findCommonStringDelimiter` causing a stack overflow.
+
+## 5.6.16
+
+ * **Internal**
+  * Fix `recast` version to avoid pulling in a newer version.
+ * **New Feature**
+  * Add support for functions in `util.shouldIgnore`.
+ * **Polish**
+  * Strip flow directives in flow transformer.
+  * Add a check for out of bounds default parameters, drastically improving performance and removes engine deoptimisations.
+  * Various performance optimisations by [@samccone](https://github.com/samccone) 💅✨
+  * Delay `this` assignment when referencing this inside an arrow function pre-bare super in derived class constructors.
+  * Split up class body pushing if the constructor is in the wrong order.
+ * **Bug Fix**
+  * Fix hoisting of `ForInStatement` `init` variables in `system` module formatter.
+  * `PathHoister`: Don't hoist to the same function as their original paths function parent.
+  * `PathHoister`: Push each violation paths ancestry to the breakOnScopePaths collection to avoid constant hoisting to nested paths.fix tail call recursion on functions with less arguments than parameters.
+  * Disallow `super.*` before `super()` in derived class constructors.
+  * Properly regenerate scope for replaced nodes. Thanks [@loganfsmyth](https://github.com/loganfsmyth)!
+  * Move up template literal simplification logic to avoid breaking on single elements.
+
+## 5.6.13-5.6.15
+
+ * Setting up automatic Travis releases.
+
+## 5.6.12
+
+ * **Bug Fix**
+  * Fix finding parent for top-level shadowed functions.
+
+## 5.6.11
+
+ ** **Internal**
+  * Merge `es6.parameters.rest` and `es6.parameters.default` transformers. See commit [c0fd4c1f9e0b18231f585c4fa793e4cb0e01aed1](https://github.com/babel/babel/commit/c0fd4c1f9e0b18231f585c4fa793e4cb0e01aed1) for more info.
+
+## 5.6.10
+
+ * **Bug Fix**
+  * Fix faulty internal require check.
+ * **Polish**
+  * Add support for trailing commas in arrow function parameter lists.
+
+## 5.6.8
+
+ * **Bug Fix**
+  * Fix binary expressions colliding with unary expression operators in compact mode.
+  * Fix node properties being set to `null` when using computed properties.
+
+## 5.6.7
+
+ * **Bug Fix**
+  * Fix hoisting of `ForXStatement` `left` `var`s when inserting a block scoping IIFE.
+ * **Polish**
+  * Combine all leading computed property initialisers into the root object in loose mode.
+ * **Internal**
+  * Deprecate returning of replacement strings from visitor methods.
+
+## 5.6.6
+
+ * **Bug Fix**
+  * Fix weird parser bug where `void` type annotations were being parsed as keywords causing the tokeniser to lose track of context.
+
+## 5.6.5
+
+ * **Bug Fix**
+  * Fix nested functions causing rest parameter optimisation to not properly detect when it should deopt on a reference.
+ * **Internal**
+  * Update Regenerator `0.8.31`.
+
 ## 5.6.4
 
  * **Internal**

CONTRIBUTING.md

@@ -113,8 +113,6 @@ your [`$PATH`](http://unix.stackexchange.com/questions/26047/how-to-correctly-ad
 
 + [js-tokens](http://ghub.io/js-tokens) This is used to get tokens for syntax error highlighting.
 
-+ [leven](http://ghub.io/leven) A levenstein algorithm to determine how close a word is to another. This is used to offer suggestions when using the utility.undeclaredVariableCheck transformer.
-
 + [line-numbers](http://ghub.io/line-numbers) Used to produce the code frames in syntax errors.
 
 + [lodash](http://ghub.io/lodash) Used for various utilities.
@@ -145,8 +143,11 @@ your [`$PATH`](http://unix.stackexchange.com/questions/26047/how-to-correctly-ad
 
 + [trim-right](http://ghub.io/trim-right) Trims the rightside whitespace.
 
-+ [user-home](http://ghub.io/user-home) Gets the users home directory. This is used to resolve the babel-node/babel/register cache.
++ [path-exists](https://www.npmjs.com/package/path-exists) Checks if a path exists. (replaces the deprecated `fs.exists` methods)
 
++ [home-or-tmp](https://github.com/sindresorhus/home-or-tmp) Gets the user home directory with fallback to the system temporary directory. This is used to resolve the babel-node/babel/register cache.
+
++ [resolve](https://www.npmjs.com/package/resolve) Implements the [`require.resolve()` algorithm](http://nodejs.org/docs/v0.12.0/api/all.html#all_require_resolve) such that we can `require.resolve()` on behalf of a file asynchronously and synchronously.
 
 #### Code Standards
 

Makefile

@@ -9,7 +9,7 @@ BROWSERIFY_IGNORE = -i esprima-fb
 
 export NODE_ENV = test
 
-.PHONY: clean test test-cov test-clean test-travis test-simple test-all test-browser test-parser publish build bootstrap publish-core publish-runtime build-core watch-core build-core-test clean-core
+.PHONY: clean test test-cov test-clean test-travis test-simple test-all test-browser test-parser publish build bootstrap publish-core publish-runtime build-website build-core watch-core build-core-test clean-core prepublish
 
 build-core: clean-core
 	node $(BABEL_CMD) src --out-dir lib --copy-files
@@ -24,7 +24,7 @@ clean-core:
 	rm -rf lib
 
 lint:
-	eslint src/babel
+	eslint src/babel packages/babel-cli/bin
 
 build:
 	mkdir -p dist
@@ -81,34 +81,20 @@ test-browser:
 
 publish: lint
 	git pull --rebase
-
 	make test
-
 	read -p "Version: " version; \
 	npm version $$version --message "v%s"
-
-	make build
-
-	cp dist/browser.js browser.js
-	cp dist/browser.min.js browser.min.js
-
-	cp dist/polyfill.js browser-polyfill.js
-	cp dist/polyfill.min.js browser-polyfill.min.js
-
-	cp dist/external-helpers.js external-helpers.js
-	cp dist/external-helpers.min.js external-helpers.min.js
-
-	node tools/cache-templates
-	test -f templates.json
-
-	npm publish
-
 	git push --follow-tags
 
-	make publish-cli
-	make publish-runtime
-
-	rm -rf templates.json browser.js browser.min.js browser-polyfill.js browser-polyfill.min.js external-helpers.js external-helpers.min.js
+prepublish: build
+	cp dist/browser.js browser.js
+	cp dist/browser.min.js browser.min.js
+	cp dist/polyfill.js browser-polyfill.js
+	cp dist/polyfill.min.js browser-polyfill.min.js
+	cp dist/external-helpers.js external-helpers.js
+	cp dist/external-helpers.min.js external-helpers.min.js
+	node tools/cache-templates
+	test -f templates.json
 
 publish-runtime:
 	cd packages; \
@@ -117,10 +103,13 @@ publish-runtime:
 	npm publish
 
 publish-cli:
-	cd packages; \
-	node build-cli.js; \
-	cd babel-cli; \
-	npm publish
+	@./tools/publish-cli.sh
+
+build-website:
+	@./tools/build-website.sh
+
+comment-issues:
+	@./tools/comment-issues.sh
 
 bootstrap:
 	npm list --global --depth 1 babel >/dev/null 2>&1 && npm uninstall -g babel || true

README.md

@@ -1,19 +1,28 @@
 <p align="center">
   <a href="https://babeljs.io/">
-    <img alt="babel" src="https://raw.githubusercontent.com/babel/logo/master/logo.png" width="546">
+    <img alt="babel" src="https://raw.githubusercontent.com/babel/logo/master/babel.png" width="546">
   </a>
 </p>
 
 <p align="center">
-  <strong>Babel</strong> is a compiler for writing next generation JavaScript.
+  The compiler for writing next generation JavaScript.
 </p>
 
 <p align="center">
-  For questions and support please visit the <a href="https://babel-slack.herokuapp.com">slack channel</a> or <a href="http://stackoverflow.com/questions/tagged/babeljs">StackOverflow</a>. The Babel issue tracker is <strong>exclusively</strong> for bug reports and feature requests.
+  <a href="https://travis-ci.org/babel/babel"><img alt="Build Status" src="https://img.shields.io/travis/babel/babel.svg?style=flat"></a>
+  <a href="http://badge.fury.io/js/babel-core"><img alt="npm version" src="https://badge.fury.io/js/babel-core.svg"></a>
+  <a href="https://npmjs.org/package/babel-core"><img alt="Downloads" src="http://img.shields.io/npm/dm/babel-core.svg"></a>
 </p>
 
 <p align="center">
-  Issues without instructions to reproduce <strong>will be immediately closed<strong>.
+  <a href="http://issuestats.com/github/babel/babel"><img alt="Issue Stats" src="http://issuestats.com/github/babel/babel/badge/pr?style=flat"></a>
+  <a href="http://issuestats.com/github/babel/babel"><img alt="Issue Stats" src="http://issuestats.com/github/babel/babel/badge/issue?style=flat"></a>
+</p>
+
+----
+
+<p align="center">
+  For questions and support please visit the <a href="https://babel-slack.herokuapp.com">Slack community</a> or <a href="http://stackoverflow.com/questions/tagged/babeljs">StackOverflow</a>. The Babel issue tracker is <strong>exclusively</strong> for bug reports and feature requests.
 </p>
 
 <p align="center">

doc/node-props.md

@@ -1,5 +1,5 @@
 # Properties of nodes
-These are properties babel stores in AST node objects for internal use, as opposed to properties that are part of the AST spec (ESTree at the time of this writing).
+These are properties babel stores in AST node objects for internal use, as opposed to properties that are part of the AST spec ([ESTree](https://github.com/estree/estree) at the time of this writing).
 
 ## `_blockHoist`
 `node._blockHoist != null` triggers the [block-hoist transformer](/src/babel/transformation/transformers/internal/block-hoist.js). Value should be `true` or an integer in the range `0..3`. `true` is equivalent to `2`. The value indicates whether the node should be hoisted and to what degree. See the source code for more detailed information.
@@ -8,4 +8,4 @@ These are properties babel stores in AST node objects for internal use, as oppos
 Stores a representation of a node's position in the tree and relationship to other nodes.
 
 ## `shadow`
-A truthy value on a function node triggers the [shadow-functions transformer](/src/babel/transformation/transformers/internal/shadow-functions.js), which transforms the node so that it references (or inherits) `arguments` and `this` from the parent scope. It is invoked for arrow functions, for example.
+A truthy value on a function node triggers the [shadow-functions transformer](/src/babel/transformation/transformers/internal/shadow-functions.js), which transforms the node so that it references (or inherits) `arguments` and the `this` context from the parent scope. It is invoked for arrow functions, for example.

index.js

@@ -0,0 +1 @@
+module.exports = require("./lib/babel/api/node.js");

package.json

@@ -1,27 +1,26 @@
 {
   "name": "babel-core",
   "description": "A compiler for writing next generation JavaScript",
-  "version": "5.6.5",
+  "version": "5.6.20",
   "author": "Sebastian McKenzie <sebmck@gmail.com>",
   "homepage": "https://babeljs.io/",
   "license": "MIT",
   "repository": "babel/babel",
-  "main": "lib/babel/api/node.js",
   "browser": {
     "./lib/babel/api/register/node.js": "./lib/babel/api/register/browser.js"
   },
   "keywords": [
-    "harmony",
+    "6to5",
+    "babel",
     "classes",
-    "modules",
-    "let",
     "const",
-    "var",
     "es6",
+    "harmony",
+    "let",
+    "modules",
     "transpile",
     "transpiler",
-    "6to5",
-    "babel"
+    "var"
   ],
   "scripts": {
     "bench": "make bench",
@@ -29,9 +28,8 @@
   },
   "dependencies": {
     "acorn-jsx": "^1.0.0",
-    "ast-types": "~0.7.0",
     "babel-plugin-constant-folding": "^1.0.1",
-    "babel-plugin-dead-code-elimination": "^1.0.1",
+    "babel-plugin-dead-code-elimination": "^1.0.2",
     "babel-plugin-eval": "^1.0.1",
     "babel-plugin-inline-environment-variables": "^1.0.1",
     "babel-plugin-jscript": "^1.0.1",
@@ -57,14 +55,14 @@
     "home-or-tmp": "^1.0.0",
     "is-integer": "^1.0.4",
     "js-tokens": "1.0.1",
-    "leven": "^1.0.1",
     "line-numbers": "0.2.0",
     "lodash": "^3.6.0",
     "minimatch": "^2.0.3",
     "output-file-sync": "^1.1.0",
+    "path-exists": "^1.0.0",
     "path-is-absolute": "^1.0.0",
     "private": "^0.1.6",
-    "regenerator": "0.8.31",
+    "regenerator": "0.8.34",
     "regexpu": "^1.1.2",
     "repeating": "^1.1.2",
     "resolve": "^1.1.6",
@@ -77,11 +75,11 @@
     "trim-right": "^1.0.0"
   },
   "devDependencies": {
-    "babel": "5.5.7",
+    "babel": "5.6.10",
+    "babel-eslint": "^3.1.19",
     "browserify": "^9.0.8",
     "chai": "^2.2.0",
     "eslint": "^0.21.2",
-    "babel-eslint": "^3.1.9",
     "esvalid": "^1.1.0",
     "istanbul": "^0.3.5",
     "matcha": "^0.6.0",

packages/babel-cli/bin/_babel-node

@@ -18,9 +18,9 @@ program.option("-p, --print [code]", "Evaluate script and print result");
 program.option("-i, --ignore [regex]", "Ignore all files that match this regex when using the require hook");
 program.option("-x, --extensions [extensions]", "List of extensions to hook into [.es6,.js,.es,.jsx]");
 program.option("-r, --stage [stage]", "Enable support for specific ECMAScript stages");
-program.option("-w, --whitelist [whitelist]", "Whitelist of transformers to ONLY use", util.list);
-program.option("-b, --blacklist [blacklist]", "Blacklist of transformers to NOT use", util.list);
-program.option("-o, --optional [optional]", "List of optional transformers to enable", util.list);
+program.option("-w, --whitelist [whitelist]", "Whitelist of transformers separated by comma to ONLY use", util.list);
+program.option("-b, --blacklist [blacklist]", "Blacklist of transformers separated by comma to NOT use", util.list);
+program.option("-o, --optional [optional]", "List of optional transformers separated by comma to enable", util.list);
 
 var pkg = require("../package.json");
 program.version(pkg.version);
@@ -41,6 +41,7 @@ babel.register({
 //
 
 var _eval = function (code, filename) {
+  code = code.trim();
   if (!code) return undefined;
 
   code = babel.transform(code, {

packages/babel-cli/bin/babel-plugin/index.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
-var readline = require("readline");
-var child    = require("child_process");
-var path     = require("path");
-var fs       = require("fs");
+var pathExists = require("path-exists");
+var readline   = require("readline");
+var child      = require("child_process");
+var path       = require("path");
+var fs         = require("fs");
 
 function spawn(cmd, args, callback) {
   console.log(">", cmd, args);
@@ -34,7 +35,7 @@ function spawnMultiple(cmds) {
 }
 
 function template(name, data) {
-  var source = fs.readFileSync(__dirname + "/templates/" + name, "utf8");
+  var source = fs.readFileSync(path.join(__dirname, "templates", name), "utf8");
   source = source.replace(/[A-Z_]+/g, function (key) {
     return data[key] === undefined ? key : data[key];
   });
@@ -98,7 +99,7 @@ var cmds = {
 
         write("README.md", template("README.md", templateData));
 
-        if (!fs.existsSync("src")) {
+        if (!pathExists.sync("src")) {
           fs.mkdirSync("src");
           write("src/index.js", template("index.js", templateData));
         }

packages/babel-cli/bin/babel/dir.js

@@ -1,4 +1,5 @@
 var outputFileSync = require("output-file-sync");
+var pathExists     = require("path-exists");
 var chokidar       = require("chokidar");
 var slash          = require("slash");
 var path           = require("path");
@@ -6,7 +7,7 @@ var util           = require("./util");
 var fs             = require("fs");
 var _              = require("lodash");
 
-module.exports = function (commander, filenames, opts) {
+module.exports = function (commander, filenames) {
   var write = function (src, relative) {
     // remove extension and then append back on .js
     relative = relative.replace(/\.(\w*?)$/, "") + ".js";
@@ -27,7 +28,7 @@ module.exports = function (commander, filenames, opts) {
 
     outputFileSync(dest, data.code);
 
-    console.log(src + " -> " + dest);
+    util.log(src + " -> " + dest);
   };
 
   var handleFile = function (src, filename) {
@@ -41,7 +42,7 @@ module.exports = function (commander, filenames, opts) {
   };
 
   var handle = function (filename) {
-    if (!fs.existsSync(filename)) return;
+    if (!pathExists.sync(filename)) return;
 
     var stat = fs.statSync(filename);
 

packages/babel-cli/bin/babel/file.js

@@ -1,4 +1,5 @@
 var convertSourceMap = require("convert-source-map");
+var pathExists       = require("path-exists");
 var sourceMap        = require("source-map");
 var chokidar         = require("chokidar");
 var slash            = require("slash");
@@ -100,7 +101,7 @@ module.exports = function (commander, filenames, opts) {
     results = [];
 
     _.each(filenames, function (filename) {
-      if (!fs.existsSync(filename)) return;
+      if (!pathExists.sync(filename)) return;
 
       var stat = fs.statSync(filename);
       if (stat.isDirectory()) {
@@ -134,7 +135,7 @@ module.exports = function (commander, filenames, opts) {
         ignoreInitial: true
       }).on("all", function (type, filename) {
         if (type === "add" || type === "change") {
-          console.log(type, filename);
+          util.log(type + " " + filename);
           try {
             walk();
           } catch (err) {

packages/babel-cli/bin/babel/index.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 
+require("babel-core");
+
 var moduleFormatters = require("babel-core/lib/babel/transformation/modules");
+var pathExists       = require("path-exists");
 var commander        = require("commander");
 var transform        = require("babel-core").transform;
 var kebabCase        = require("lodash/string/kebabCase");
@@ -9,7 +12,6 @@ var util             = require("babel-core").util;
 var uniq             = require("lodash/array/uniq");
 var each             = require("lodash/collection/each");
 var keys             = require("lodash/object/keys");
-var fs               = require("fs");
 var glob             = require("glob");
 
 each(options, function (option, key) {
@@ -43,6 +45,7 @@ commander.option("-w, --watch", "Recompile files on changes");
 commander.option("-o, --out-file [out]", "Compile all input files into a single file");
 commander.option("-d, --out-dir [out]", "Compile an input directory of modules into an output directory");
 commander.option("-D, --copy-files", "When compiling a directory copy over non-compilable files");
+commander.option("-q, --quiet", "Don't log anything");
 
 commander.on("--help", function () {
   var outKeys = function (title, obj) {
@@ -65,7 +68,7 @@ commander.on("--help", function () {
 });
 
 var pkg = require("../../package.json");
-commander.version(pkg.version);
+commander.version(pkg.version + " (babel-core " + require("babel-core").version + ")");
 commander.usage("[options] <files ...>");
 commander.parse(process.argv);
 
@@ -88,7 +91,7 @@ var filenames = commander.args.reduce(function (globbed, input) {
 filenames = uniq(filenames);
 
 each(filenames, function (filename) {
-  if (!fs.existsSync(filename)) {
+  if (!pathExists.sync(filename)) {
     errors.push(filename + " doesn't exist");
   }
 });

packages/babel-cli/bin/babel/util.js

@@ -25,6 +25,10 @@ exports.addSourceMappingUrl = function (code, loc) {
   return code + "\n//# sourceMappingURL=" + path.basename(loc);
 };
 
+exports.log = function (msg) {
+  if (!commander.quiet) console.log(msg);
+};
+
 exports.transform = function (filename, code, opts) {
   opts = _.defaults(opts || {}, index.opts);
   opts.filename = filename;

packages/babel-cli/package.json

@@ -1,14 +1,12 @@
 {
   "name": "babel",
   "description": "Turn ES6 code into readable vanilla ES5 with source maps",
-  "version": "5.6.4",
   "author": "Sebastian McKenzie <sebmck@gmail.com>",
   "homepage": "https://babeljs.io/",
   "license": "MIT",
   "repository": "babel/babel",
   "preferGlobal": true,
   "dependencies": {
-    "babel-core": "^5.6.4",
     "chokidar": "^1.0.0",
     "commander": "^2.6.0",
     "convert-source-map": "^1.1.0",
@@ -16,6 +14,7 @@
     "glob": "^5.0.5",
     "lodash": "^3.2.0",
     "output-file-sync": "^1.1.0",
+    "path-exists": "^1.0.0",
     "path-is-absolute": "^1.0.0",
     "source-map": "^0.4.0",
     "slash": "^1.0.0"
@@ -26,4 +25,4 @@
     "babel-external-helpers": "./bin/babel-external-helpers",
     "babel-plugin": "./bin/babel-plugin/index.js"
   }
-}
+}

packages/babel-runtime/package.json

@@ -1,11 +1,10 @@
 {
   "name": "babel-runtime",
   "description": "babel selfContained runtime",
-  "version": "5.6.4",
   "license": "MIT",
   "repository": "babel/babel",
   "author": "Sebastian McKenzie <sebmck@gmail.com>",
   "dependencies": {
     "core-js": "^0.9.0"
   }
-}
+}

packages/build-runtime.js

@@ -73,7 +73,6 @@ each(File.helpers, function (helperName) {
 writeFile("regenerator/index.js", readFile("regenerator/runtime-module", true));
 writeFile("regenerator/runtime.js", selfContainify(readFile("regenerator/runtime")));
 
-//
 
 var coreDefinitions = require("babel-plugin-runtime/lib/definitions");
 
@@ -93,6 +92,5 @@ each(paths, function (path) {
   writeFile("core-js/" + path + ".js", defaultify('require("core-js/library/fn/' + path + '")'));
 });
 
-//
 
 updatePackage();

src/README.md

@@ -0,0 +1,27 @@
+## Welcome to the Babel Codebase
+
+Babel is broken down into three parts:
+
+- Parsing
+- [Transformation](babel/transformation/)
+- [Generation](babel/generation/)
+
+**Parsing** is the process of turning a piece of code into an [ESTree spec](https://github.com/estree/estree) compatible AST (Abstract
+Syntax Tree) which is a tree-like object of nodes that _describes_ the code.
+This makes it easier to transform the code over direct string manpulation.
+
+**Transformation** is the process of taking an AST and manipulating it into
+a new one. For example, Babel might take an ES2015 ArrowFunction and transform
+it into a normal Function which will work in ES5 environments.
+
+**Generation** is the process of turning an AST back into code. After Babel is
+done transforming the AST, the generation takes over to return normal code.
+
+---
+
+Babel's parsing step is done by [Acorn](https://github.com/marijnh/acorn). However, because Babel is implementing
+future standards it maintains a [fork of Acorn](acorn/) in order to do it's job. You can
+see that fork in the "acorn" folder.
+
+The transformation and generation steps are both handled inside of the Babel
+codebase itself, which is in the "babel" folder here.

src/acorn/plugins/flow.js

@@ -15,6 +15,15 @@ pp.expectRelational = function (op) {
   }
 }
 
+pp.flow_parseTypeInitialiser = function (tok) {
+  var oldInType = this.inType
+  this.inType = true
+  this.expect(tok || tt.colon)
+  var type = this.flow_parseType()
+  this.inType = oldInType
+  return type;
+}
+
 pp.flow_parseDeclareClass = function (node) {
   this.next()
   this.flow_parseInterfaceish(node, true)
@@ -40,9 +49,7 @@ pp.flow_parseDeclareFunction = function (node) {
   typeNode.params = tmp.params
   typeNode.rest = tmp.rest
   this.expect(tt.parenR)
-
-  this.expect(tt.colon)
-  typeNode.returnType = this.flow_parseType()
+  typeNode.returnType = this.flow_parseTypeInitialiser()
 
   typeContainer.typeAnnotation = this.finishNode(typeNode, "FunctionTypeAnnotation")
   id.typeAnnotation = this.finishNode(typeContainer, "TypeAnnotation")
@@ -153,15 +160,7 @@ pp.flow_parseTypeAlias = function (node) {
     node.typeParameters = null
   }
 
-  var oldInType = this.inType;
-  this.inType = true;
-
-  this.expect(tt.eq)
-
-  node.right = this.flow_parseType()
-
-  this.inType = oldInType;
-
+  node.right = this.flow_parseTypeInitialiser(tt.eq)
   this.semicolon()
 
   return this.finishNode(node, "TypeAlias")
@@ -214,11 +213,9 @@ pp.flow_parseObjectTypeIndexer = function (node, isStatic) {
 
   this.expect(tt.bracketL)
   node.id = this.flow_parseObjectPropertyKey()
-  this.expect(tt.colon)
-  node.key = this.flow_parseType()
+  node.key = this.flow_parseTypeInitialiser()
   this.expect(tt.bracketR)
-  this.expect(tt.colon)
-  node.value = this.flow_parseType()
+  node.value = this.flow_parseTypeInitialiser()
 
   this.flow_objectTypeSemicolon()
   return this.finishNode(node, "ObjectTypeIndexer")
@@ -245,8 +242,7 @@ pp.flow_parseObjectTypeMethodish = function (node) {
     node.rest = this.flow_parseFunctionTypeParam()
   }
   this.expect(tt.parenR)
-  this.expect(tt.colon)
-  node.returnType = this.flow_parseType()
+  node.returnType = this.flow_parseTypeInitialiser()
 
   return this.finishNode(node, "FunctionTypeAnnotation")
 }
@@ -265,7 +261,7 @@ pp.flow_parseObjectTypeCallProperty = function (node, isStatic) {
   var valueNode = this.startNode()
   node.static = isStatic
   node.value = this.flow_parseObjectTypeMethodish(valueNode)
-    this.flow_objectTypeSemicolon()
+  this.flow_objectTypeSemicolon()
   return this.finishNode(node, "ObjectTypeCallProperty")
 }
 
@@ -310,9 +306,8 @@ pp.flow_parseObjectType = function (allowStatic) {
         if (this.eat(tt.question)) {
           optional = true
         }
-        this.expect(tt.colon)
         node.key = propertyKey
-        node.value = this.flow_parseType()
+        node.value = this.flow_parseTypeInitialiser()
         node.optional = optional
         node.static = isStatic
         this.flow_objectTypeSemicolon()
@@ -352,12 +347,6 @@ pp.flow_parseGenericType = function (start, id) {
   return this.finishNode(node, "GenericTypeAnnotation")
 }
 
-pp.flow_parseVoidType = function () {
-  var node = this.startNode()
-  this.expect(tt._void)
-  return this.finishNode(node, "VoidTypeAnnotation")
-}
-
 pp.flow_parseTypeofType = function () {
   var node = this.startNode()
   this.expect(tt._typeof)
@@ -386,9 +375,8 @@ pp.flow_parseFunctionTypeParam = function () {
   if (this.eat(tt.question)) {
     optional = true
   }
-  this.expect(tt.colon)
   node.optional = optional
-  node.typeAnnotation = this.flow_parseType()
+  node.typeAnnotation = this.flow_parseTypeInitialiser()
   return this.finishNode(node, "FunctionTypeParam")
 }
 
@@ -411,6 +399,9 @@ pp.flow_identToTypeAnnotation = function (start, node, id) {
     case "any":
       return this.finishNode(node, "AnyTypeAnnotation")
 
+    case "void":
+      return this.finishNode(node, "VoidTypeAnnotation")
+
     case "bool":
     case "boolean":
       return this.finishNode(node, "BooleanTypeAnnotation")
@@ -524,14 +515,8 @@ pp.flow_parsePrimaryType = function () {
       return this.finishNode(node, "StringLiteralTypeAnnotation")
 
     default:
-      if (this.type.keyword) {
-        switch (this.type.keyword) {
-          case "void":
-            return this.flow_parseVoidType()
-
-          case "typeof":
-            return this.flow_parseTypeofType()
-        }
+      if (this.type.keyword === "typeof") {
+        return this.flow_parseTypeofType()
       }
   }
 
@@ -588,13 +573,7 @@ pp.flow_parseType = function () {
 
 pp.flow_parseTypeAnnotation = function () {
   var node = this.startNode()
-
-  var oldInType = this.inType
-  this.inType = true
-  this.expect(tt.colon)
-  node.typeAnnotation = this.flow_parseType()
-  this.inType = oldInType
-
+  node.typeAnnotation = this.flow_parseTypeInitialiser()
   return this.finishNode(node, "TypeAnnotation")
 }
 
@@ -694,6 +673,18 @@ acorn.plugins.flow = function (instance) {
     }
   })
 
+  // don't consider `void` to be a keyword as then it'll use the void token type
+  // and set startExpr
+  instance.extend("isKeyword", function (inner) {
+    return function(name) {
+      if (this.inType && name === "void") {
+        return false
+      } else {
+        return inner.call(this, name)
+      }
+    }
+  })
+
   instance.extend("readToken", function (inner) {
     return function(code) {
       if (this.inType && (code === 62 || code === 60)) {
@@ -800,16 +791,15 @@ acorn.plugins.flow = function (instance) {
 
   instance.extend("parseImportSpecifiers", function (inner) {
     return function (node) {
-      node.isType = false
-      if (this.isContextual("type")) {
-        var start = this.markPosition()
-        var typeId = this.parseIdent()
-        if ((this.type === tt.name && this.value !== "from") || this.type === tt.braceL || this.type === tt.star) {
-          node.isType = true
-        } else {
-          node.specifiers.push(this.parseImportSpecifierDefault(typeId, start))
-          if (this.isContextual("from")) return
-          this.eat(tt.comma)
+      node.importKind = "value"
+      var kind =
+        (this.type === tt._typeof ? "typeof" :
+        (this.isContextual("type") ? "type" : null))
+      if (kind) {
+        var lh = this.lookahead()
+        if ((lh.type === tt.name && lh.value !== "from") || lh.type === tt.braceL || lh.type === tt.star) {
+          this.next()
+          node.importKind = kind
         }
       }
       inner.call(this, node)

src/acorn/src/expression.js

@@ -432,9 +432,18 @@ pp.parseParenAndDistinguishExpression = function(start, isAsync, canBeArrow) {
     }
 
     let innerStart = this.markPosition(), exprList = [], first = true
-    let refShorthandDefaultPos = {start: 0}, spreadStart, innerParenStart
+    let refShorthandDefaultPos = {start: 0}, spreadStart, innerParenStart, optionalCommaStart
     while (this.type !== tt.parenR) {
-      first ? first = false : this.expect(tt.comma)
+      if (first) {
+        first = false;
+      } else {
+        this.expect(tt.comma)
+        if (this.type === tt.parenR && this.options.features["es7.trailingFunctionCommas"]) {
+          optionalCommaStart = this.start
+          break
+        }
+      }
+
       if (this.type === tt.ellipsis) {
         let spreadNodeStart = this.markPosition()
         spreadStart = this.start
@@ -462,6 +471,7 @@ pp.parseParenAndDistinguishExpression = function(start, isAsync, canBeArrow) {
         this.unexpected(this.lastTokStart)
       }
     }
+    if (optionalCommaStart) this.unexpected(optionalCommaStart)
     if (spreadStart) this.unexpected(spreadStart)
     if (refShorthandDefaultPos.start) this.unexpected(refShorthandDefaultPos.start)
 

src/acorn/src/lookahead.js

@@ -19,7 +19,11 @@ var STATE_KEYS = [
   "exprAllowed",
   "potentialArrowAt",
   "currLine",
-  "input"
+  "input",
+  "inType",
+  "inFunction",
+  "inGenerator",
+  "labels"
 ];
 
 pp.getState = function () {
@@ -29,6 +33,7 @@ pp.getState = function () {
     state[key] = this[key]
   }
   state.context = this.context.slice()
+  state.labels = this.labels.slice()
   return state
 };
 

src/acorn/src/options.js

@@ -1,4 +1,4 @@
-import {has, isArray} from "./util"
+import {has} from "./util"
 import {SourceLocation} from "./location"
 
 // A second optional argument can be given to further configure
@@ -94,11 +94,11 @@ export function getOptions(opts) {
   for (let opt in defaultOptions)
     options[opt] = opts && has(opts, opt) ? opts[opt] : defaultOptions[opt]
 
-  if (isArray(options.onToken)) {
+  if (Array.isArray(options.onToken)) {
     let tokens = options.onToken
     options.onToken = (token) => tokens.push(token)
   }
-  if (isArray(options.onComment))
+  if (Array.isArray(options.onComment))
     options.onComment = pushComment(options, options.onComment)
 
   return options

src/acorn/src/state.js

@@ -4,11 +4,11 @@ import {lineBreak} from "./whitespace"
 
 export function Parser(options, input, startPos) {
   this.options = options
-  this.loadPlugins(this.options.plugins)
   this.sourceFile = this.options.sourceFile || null
   this.isKeyword = keywords[this.options.ecmaVersion >= 6 ? 6 : 5]
   this.isReservedWord = reservedWords[this.options.ecmaVersion]
   this.input = input
+  this.loadPlugins(this.options.plugins)
 
   // Set up token state
 

src/acorn/src/tokentype.js

@@ -112,7 +112,7 @@ kw("case", beforeExpr)
 kw("catch")
 kw("continue")
 kw("debugger")
-kw("default")
+kw("default", beforeExpr)
 kw("do", {isLoop: true})
 kw("else", beforeExpr)
 kw("finally")

src/acorn/src/util.js

@@ -1,7 +1,3 @@
-export function isArray(obj) {
-  return Object.prototype.toString.call(obj) === "[object Array]"
-}
-
 // Checks if an object has a property.
 
 export function has(obj, propName) {

src/babel/README.md

@@ -0,0 +1,4 @@
+## Diving into Babel
+
+If you look around in the various directories in here you'll find some details
+about the organization of the Babel codebase.

src/babel/api/README.md

@@ -0,0 +1,18 @@
+## API
+
+In this directory you'll find all the public interfaces to using Babel for both
+node and the browser.
+
+### Node
+
+There are two ways people use Babel within Node, they either are manipulating
+strings of code with `babel.transform` or `babel.parse`, they also might be
+running their code through Babel before execution via `register` or `polyfill`.
+
+### Browser
+
+Usage of Babel in the browser is extremely uncommon and in most cases
+considered A Bad Idea™. However it works by loading `<script>`'s with XHR,
+transforming them and then executing them. These `<script>`'s need to have a
+`type` of "text/ecmascript-6", "text/babel", or "module" ("text/6to5" exists as
+well for legacy reasons).

src/babel/api/browser.js

@@ -3,16 +3,32 @@
 require("./node");
 var transform = module.exports = require("../transformation");
 
+/**
+ * Add `options` and `version` to `babel` global.
+ */
+
 transform.options = require("../transformation/file/options");
 transform.version = require("../../../package").version;
 
+/**
+ * Add `transform` api to `babel` global.
+ */
+
 transform.transform = transform;
 
+/**
+ * Tranform and execute script, adding in inline sourcemaps.
+ */
+
 transform.run = function (code, opts = {}) {
   opts.sourceMaps = "inline";
   return new Function(transform(code, opts).code)();
 };
 
+/**
+ * Load scripts via xhr, and `transform` when complete (optional).
+ */
+
 transform.load = function (url, callback, opts = {}, hold) {
   opts.filename = opts.filename || url;
 
@@ -20,6 +36,10 @@ transform.load = function (url, callback, opts = {}, hold) {
   xhr.open("GET", url, true);
   if ("overrideMimeType" in xhr) xhr.overrideMimeType("text/plain");
 
+  /**
+   * When successfully loaded, transform (optional), and call `callback`.
+   */
+
   xhr.onreadystatechange = function () {
     if (xhr.readyState !== 4) return;
 
@@ -36,11 +56,22 @@ transform.load = function (url, callback, opts = {}, hold) {
   xhr.send(null);
 };
 
+/**
+ * Load and transform all scripts of `types`.
+ *
+ * @example
+ * <script type="module"></script>
+ */
+
 var runScripts = function () {
   var scripts = [];
   var types   = ["text/ecmascript-6", "text/6to5", "text/babel", "module"];
   var index   = 0;
 
+  /**
+   * Transform and execute script. Ensures correct load order.
+   */
+
   var exec = function () {
     var param = scripts[index];
     if (param instanceof Array) {
@@ -50,6 +81,10 @@ var runScripts = function () {
     }
   };
 
+  /**
+   * Load, transform, and execute all scripts.
+   */
+
   var run = function (script, i) {
     var opts = {};
 
@@ -64,7 +99,9 @@ var runScripts = function () {
     }
   };
 
-  var _scripts = global.document .getElementsByTagName("script");
+  // Collect scripts with Babel `types`.
+
+  var _scripts = global.document.getElementsByTagName("script");
 
   for (var i = 0; i < _scripts.length; ++i) {
     var _script = _scripts[i];
@@ -78,6 +115,10 @@ var runScripts = function () {
   exec();
 };
 
+/**
+ * Register load event to transform and execute scripts.
+ */
+
 if (global.addEventListener) {
   global.addEventListener("DOMContentLoaded", runScripts, false);
 } else if (global.attachEvent) {

src/babel/api/node.js

@@ -19,16 +19,28 @@ export { version } from "../../../package";
 import * as t from "../types";
 export { t as types };
 
+/**
+ * Register Babel and polyfill globally.
+ */
+
 export function register(opts?: Object) {
   var callback = require("./register/node-polyfill");
   if (opts != null) callback(opts);
   return callback;
 }
 
+/**
+ * Register polyfill globally.
+ */
+
 export function polyfill() {
   require("../polyfill");
 }
 
+/**
+ * Asynchronously transform `filename` with optional `opts`, calls `callback` when complete.
+ */
+
 export function transformFile(filename: string, opts?: Object, callback: Function) {
   if (isFunction(opts)) {
     callback = opts;
@@ -52,11 +64,19 @@ export function transformFile(filename: string, opts?: Object, callback: Functio
   });
 }
 
+/**
+ * Synchronous form of `transformFile`.
+ */
+
 export function transformFileSync(filename: string, opts?: Object = {}) {
   opts.filename = filename;
   return transform(fs.readFileSync(filename, "utf8"), opts);
 }
 
+/**
+ * Parse script with Babel's parser.
+ */
+
 export function parse(code, opts = {}) {
   opts.allowHashBang = true;
   opts.sourceType = "module";

src/babel/api/register/cache.js

@@ -1,21 +1,30 @@
 import path from "path";
 import fs from "fs";
 import homeOrTmp from "home-or-tmp";
+import pathExists from "path-exists";
 
 const FILENAME = process.env.BABEL_CACHE_PATH || path.join(homeOrTmp, ".babel.json");
 var data = {};
 
+/**
+ * Write stringified cache to disk.
+ */
+
 export function save() {
   fs.writeFileSync(FILENAME, JSON.stringify(data, null, "  "));
 }
 
+/**
+ * Load cache from disk and parse.
+ */
+
 export function load() {
   if (process.env.BABEL_DISABLE_CACHE) return;
 
   process.on("exit", save);
   process.nextTick(save);
 
-  if (!fs.existsSync(FILENAME)) return;
+  if (!pathExists.sync(FILENAME)) return;
 
   try {
     data = JSON.parse(fs.readFileSync(FILENAME));
@@ -24,6 +33,10 @@ export function load() {
   }
 }
 
+/**
+ * Retrieve data from cache.
+ */
+
 export function get() {
   return data;
 }

src/babel/api/register/node.js

@@ -1,6 +1,6 @@
 import sourceMapSupport from "source-map-support";
 import * as registerCache from "./cache";
-import resolveRc from "../../transformation/file/options/resolve-rc";
+import OptionManager from "../../transformation/file/options/option-manager";
 import extend from "lodash/object/extend";
 import * as babel from "../node";
 import each from "lodash/collection/each";
@@ -8,6 +8,10 @@ import * as util from  "../../util";
 import fs from "fs";
 import path from "path";
 
+/**
+ * Install sourcemaps into node.
+ */
+
 sourceMapSupport.install({
   handleUncaughtExceptions: false,
   retrieveSourceMap(source) {
@@ -23,12 +27,16 @@ sourceMapSupport.install({
   }
 });
 
-//
+/**
+ * Load and setup cache.
+ */
 
 registerCache.load();
 var cache = registerCache.get();
 
-//
+/**
+ * Store options.
+ */
 
 var transformOpts = {};
 
@@ -40,22 +48,32 @@ var maps          = {};
 
 var cwd = process.cwd();
 
+/**
+ * Get path from `filename` relative to the current working directory.
+ */
+
 var getRelativePath = function (filename){
   return path.relative(cwd, filename);
 };
 
+/**
+ * Get last modified time for a `filename`.
+ */
+
 var mtime = function (filename) {
   return +fs.statSync(filename).mtime;
 };
 
+/**
+ * Compile a `filename` with optional `opts`.
+ */
+
 var compile = function (filename, opts = {}) {
   var result;
 
-  opts = extend(opts, transformOpts);
-
-  // this will be done when the file is transformed anyway but we need all
-  // the options so we can generate the cache key
-  resolveRc(filename, opts);
+  var optsManager = new OptionManager;
+  optsManager.mergeOptions(transformOpts);
+  opts = optsManager.init(opts);
 
   var cacheKey = `${filename}:${JSON.stringify(opts)}:${babel.version}`;
 
@@ -86,6 +104,10 @@ var compile = function (filename, opts = {}) {
   return result.code;
 };
 
+/**
+ * Test if a `filename` should be ignored by Babel.
+ */
+
 var shouldIgnore = function (filename) {
   if (!ignore && !only) {
     return getRelativePath(filename).split(path.sep).indexOf("node_modules") >= 0;
@@ -94,6 +116,10 @@ var shouldIgnore = function (filename) {
   }
 };
 
+/**
+ * Monkey patch istanbul if it is running so that it works properly.
+ */
+
 var istanbulMonkey = {};
 
 if (process.env.running_under_istanbul) {
@@ -115,15 +141,27 @@ if (process.env.running_under_istanbul) {
   };
 }
 
+/**
+ * Replacement for the loader for istanbul.
+ */
+
 var istanbulLoader = function (m, filename, old) {
   istanbulMonkey[filename] = true;
   old(m, filename);
 };
 
+/**
+ * Default loader.
+ */
+
 var normalLoader = function (m, filename) {
   m._compile(compile(filename), filename);
 };
 
+/**
+ * Register a loader for an extension.
+ */
+
 var registerExtension = function (ext) {
   var old = oldHandlers[ext] || oldHandlers[".js"] || require.extensions[".js"];
 
@@ -139,6 +177,10 @@ var registerExtension = function (ext) {
   };
 };
 
+/**
+ * Register loader for given extensions.
+ */
+
 var hookExtensions = function (_exts) {
   each(oldHandlers, function (old, ext) {
     if (old === undefined) {
@@ -156,8 +198,16 @@ var hookExtensions = function (_exts) {
   });
 };
 
+/**
+ * Register loader for default extensions.
+ */
+
 hookExtensions(util.canCompile.EXTENSIONS);
 
+/**
+ * Update options at runtime.
+ */
+
 export default function (opts = {}) {
   if (opts.only != null) only = util.arrayify(opts.only, util.regexify);
   if (opts.ignore != null) ignore = util.arrayify(opts.ignore, util.regexify);

src/babel/generation/README.md

@@ -0,0 +1,16 @@
+## Generation
+
+Here is Babel's code generator, here you'll find all of the code to turn an AST
+back into a string of code.
+
+[TBD: To Be Documented:]
+
+- Code Generator
+- Buffer
+- Source Maps
+  - Position
+- Printer
+- Code Style
+  - Whitespace
+  - Parenthesis
+- Generators

src/babel/generation/buffer.js

@@ -4,6 +4,10 @@ import isBoolean from "lodash/lang/isBoolean";
 import includes from "lodash/collection/includes";
 import isNumber from "lodash/lang/isNumber";
 
+/**
+ * Buffer for collecting generated output.
+ */
+
 export default class Buffer {
   constructor(position, format) {
     this.position = position;
@@ -12,10 +16,18 @@ export default class Buffer {
     this.buf      = "";
   }
 
+  /**
+   * Get the current trimmed buffer.
+   */
+
   get() {
     return trimRight(this.buf);
   }
 
+  /**
+   * Get the current indent.
+   */
+
   getIndent() {
     if (this.format.compact || this.format.concise) {
       return "";
@@ -24,43 +36,80 @@ export default class Buffer {
     }
   }
 
+  /**
+   * Get the current indent size.
+   */
+
   indentSize() {
     return this.getIndent().length;
   }
 
+  /**
+   * Increment indent size.
+   */
+
   indent() {
     this._indent++;
   }
 
+  /**
+   * Decrement indent size.
+   */
+
   dedent() {
     this._indent--;
   }
 
+  /**
+   * Add a semicolon to the buffer.
+   */
+
   semicolon() {
     this.push(";");
   }
 
+  /**
+   * Ensure last character is a semicolon.
+   */
+
   ensureSemicolon() {
     if (!this.isLast(";")) this.semicolon();
   }
 
+  /**
+   * Add a right brace to the buffer.
+   */
+
   rightBrace() {
     this.newline(true);
     this.push("}");
   }
 
+  /**
+   * Add a keyword to the buffer.
+   */
+
   keyword(name) {
     this.push(name);
     this.space();
   }
 
-  space() {
-    if (this.format.compact) return;
-    if (this.buf && !this.isLast(" ") && !this.isLast("\n")) {
+  /**
+   * Add a space to the buffer unless it is compact (override with force).
+   */
+
+  space(force?) {
+    if (!force && this.format.compact) return;
+
+    if (force || this.buf && !this.isLast(" ") && !this.isLast("\n")) {
       this.push(" ");
     }
   }
 
+  /**
+   * Remove the last character.
+   */
+
   removeLast(cha) {
     if (this.format.compact) return;
     if (!this.isLast(cha)) return;
@@ -69,6 +118,11 @@ export default class Buffer {
     this.position.unshift(cha);
   }
 
+  /**
+   * Add a newline (or many newlines), maintaining formatting.
+   * Strips multiple newlines if removeLast is true.
+   */
+
   newline(i, removeLast) {
     if (this.format.compact || this.format.retainLines) return;
 
@@ -99,6 +153,10 @@ export default class Buffer {
     this._newline(removeLast);
   }
 
+  /**
+   * Adds a newline unless there is already two previous newlines.
+   */
+
   _newline(removeLast) {
     // never allow more than two lines
     if (this.endsWith("\n\n")) return;
@@ -135,6 +193,10 @@ export default class Buffer {
     }
   }
 
+  /**
+   * Push a string to the buffer, maintaining indentation and newlines.
+   */
+
   push(str, noIndent) {
     if (!this.format.compact && this._indent && !noIndent && str !== "\n") {
       // we have an indent level and we aren't pushing a newline
@@ -150,15 +212,31 @@ export default class Buffer {
     this._push(str);
   }
 
+  /**
+   * Push a string to the buffer.
+   */
+
   _push(str) {
     this.position.push(str);
     this.buf += str;
   }
 
-  endsWith(str) {
-    return this.buf.slice(-str.length) === str;
+  /**
+   * Test if the buffer ends with a string.
+   */
+
+  endsWith(str, buf = this.buf) {
+    if (str.length === 1) {
+      return buf[buf.length - 1] === str;
+    } else {
+      return buf.slice(-str.length) === str;
+    }
   }
 
+  /**
+   * Test if a character is last in the buffer.
+   */
+
   isLast(cha) {
     if (this.format.compact) return false;
 

src/babel/generation/generators/README.md

@@ -0,0 +1,10 @@
+## Generators
+
+Code generation in Babel is broken down into generators by node type, they all
+live in this directory.
+
+[TBD: To Be Documented:]
+
+- How generators work
+- How to print a node
+- How generators related to one another

src/babel/generation/generators/base.js

@@ -1,11 +1,23 @@
+/**
+ * Print File.program
+ */
+
 export function File(node, print) {
   print.plain(node.program);
 }
 
+/**
+ * Print all nodes in a Program.body.
+ */
+
 export function Program(node, print) {
   print.sequence(node.body);
 }
 
+/**
+ * Print BlockStatement, collapses empty blocks, prints body.
+ */
+
 export function BlockStatement(node, print) {
   if (node.body.length === 0) {
     this.push("{}");
@@ -18,6 +30,13 @@ export function BlockStatement(node, print) {
   }
 }
 
+/**
+ * What is my purpose?
+ * Why am I here?
+ * Why are any of us here?
+ * Does any of this really matter?
+ */
+
 export function Noop() {
 
 }

src/babel/generation/generators/classes.js

@@ -1,5 +1,9 @@
+/**
+ * Print ClassDeclaration, prints decorators, typeParameters, extends, implements, and body.
+ */
+
 export function ClassDeclaration(node, print) {
-  print.list(node.decorators);
+  print.list(node.decorators, { separator: "" });
   this.push("class");
 
   if (node.id) {
@@ -24,8 +28,16 @@ export function ClassDeclaration(node, print) {
   print.plain(node.body);
 }
 
+/**
+ * Alias ClassDeclaration printer as ClassExpression.
+ */
+
 export { ClassDeclaration as ClassExpression };
 
+/**
+ * Print ClassBody, collapses empty blocks, prints body.
+ */
+
 export function ClassBody(node, print) {
   if (node.body.length === 0) {
     this.push("{}");
@@ -41,9 +53,13 @@ export function ClassBody(node, print) {
   }
 }
 
+/**
+ * Print ClassProperty, prints decorators, static, key, typeAnnotation, and value.
+ * Also: semicolons, deal with it.
+ */
 
 export function ClassProperty(node, print) {
-  print.list(node.decorators);
+  print.list(node.decorators, { separator: "" });
 
   if (node.static) this.push("static ");
   print.plain(node.key);
@@ -57,8 +73,12 @@ export function ClassProperty(node, print) {
   this.semicolon();
 }
 
+/**
+ * Print MethodDefinition, prints decorations, static, and method.
+ */
+
 export function MethodDefinition(node, print) {
-  print.list(node.decorators);
+  print.list(node.decorators, { separator: "" });
 
   if (node.static) {
     this.push("static ");

src/babel/generation/generators/comprehensions.js

@@ -1,3 +1,7 @@
+/**
+ * Prints ComprehensionBlock, prints left and right.
+ */
+
 export function ComprehensionBlock(node, print) {
   this.keyword("for");
   this.push("(");
@@ -7,6 +11,10 @@ export function ComprehensionBlock(node, print) {
   this.push(")");
 }
 
+/**
+ * Prints ComprehensionExpression, prints blocks, filter, and body. Handles generators.
+ */
+
 export function ComprehensionExpression(node, print) {
   this.push(node.generator ? "(" : "[");
 

src/babel/generation/generators/expressions.js

@@ -1,35 +1,51 @@
 import isNumber from "lodash/lang/isNumber";
 import * as t from "../../types";
 
+/**
+ * Prints UnaryExpression, prints operator and argument.
+ */
+
 export function UnaryExpression(node, print) {
-  var hasSpace = /[a-z]$/.test(node.operator);
+  var needsSpace = /[a-z]$/.test(node.operator);
   var arg = node.argument;
 
   if (t.isUpdateExpression(arg) || t.isUnaryExpression(arg)) {
-    hasSpace = true;
+    needsSpace = true;
   }
 
   if (t.isUnaryExpression(arg) && arg.operator === "!") {
-    hasSpace = false;
+    needsSpace = false;
   }
 
   this.push(node.operator);
-  if (hasSpace) this.push(" ");
+  if (needsSpace) this.push(" ");
   print.plain(node.argument);
 }
 
+/**
+ * Prints DoExpression, prints body.
+ */
+
 export function DoExpression(node, print) {
   this.push("do");
   this.space();
   print.plain(node.body);
 }
 
+/**
+ * Prints ParenthesizedExpression, prints expression.
+ */
+
 export function ParenthesizedExpression(node, print) {
   this.push("(");
   print.plain(node.expression);
   this.push(")");
 }
 
+/**
+ * Prints UpdateExpression, prints operator and argument.
+ */
+
 export function UpdateExpression(node, print) {
   if (node.prefix) {
     this.push(node.operator);
@@ -40,6 +56,10 @@ export function UpdateExpression(node, print) {
   }
 }
 
+/**
+ * Prints ConditionalExpression, prints test, consequent, and alternate.
+ */
+
 export function ConditionalExpression(node, print) {
   print.plain(node.test);
   this.space();
@@ -52,6 +72,10 @@ export function ConditionalExpression(node, print) {
   print.plain(node.alternate);
 }
 
+/**
+ * Prints NewExpression, prints callee and arguments.
+ */
+
 export function NewExpression(node, print) {
   this.push("new ");
   print.plain(node.callee);
@@ -60,42 +84,59 @@ export function NewExpression(node, print) {
   this.push(")");
 }
 
+/**
+ * Prints SequenceExpression.expressions.
+ */
+
 export function SequenceExpression(node, print) {
   print.list(node.expressions);
 }
 
+/**
+ * Prints ThisExpression.
+ */
+
 export function ThisExpression() {
   this.push("this");
 }
 
+/**
+ * Prints Super.
+ */
+
 export function Super() {
   this.push("super");
 }
 
+/**
+ * Prints Decorator, prints expression.
+ */
+
 export function Decorator(node, print) {
   this.push("@");
   print.plain(node.expression);
   this.newline();
 }
 
+/**
+ * Prints CallExpression, prints callee and arguments.
+ */
+
 export function CallExpression(node, print) {
   print.plain(node.callee);
 
   this.push("(");
 
-  var separator = ",";
-
-  var isPrettyCall = node._prettyCall && !this.format.retainLines;
+  var isPrettyCall = node._prettyCall && !this.format.retainLines && !this.format.compact;
 
+  var separator;
   if (isPrettyCall) {
-    separator += "\n";
+    separator = ",\n";
     this.newline();
     this.indent();
-  } else {
-    separator += " ";
   }
 
-  print.list(node.arguments, { separator: separator });
+  print.list(node.arguments, { separator });
 
   if (isPrettyCall) {
     this.newline();
@@ -105,6 +146,11 @@ export function CallExpression(node, print) {
   this.push(")");
 }
 
+/**
+ * Builds yield or await expression printer.
+ * Prints delegate, all, and argument.
+ */
+
 var buildYieldAwait = function (keyword) {
   return function (node, print) {
     this.push(keyword);
@@ -120,44 +166,91 @@ var buildYieldAwait = function (keyword) {
   };
 };
 
+/**
+ * Create YieldExpression and AwaitExpression printers.
+ */
+
 export var YieldExpression = buildYieldAwait("yield");
 export var AwaitExpression = buildYieldAwait("await");
 
+/**
+ * Prints EmptyStatement.
+ */
+
 export function EmptyStatement() {
   this.semicolon();
 }
 
+/**
+ * Prints ExpressionStatement, prints expression.
+ */
+
 export function ExpressionStatement(node, print) {
   print.plain(node.expression);
   this.semicolon();
 }
 
+/**
+ * Prints AssignmentPattern, prints left and right.
+ */
+
 export function AssignmentPattern(node, print) {
   print.plain(node.left);
   this.push(" = ");
   print.plain(node.right);
 }
 
+/**
+ * Prints AssignmentExpression, prints left, operator, and right.
+ */
+
 export function AssignmentExpression(node, print) {
   // todo: add cases where the spaces can be dropped when in compact mode
   print.plain(node.left);
-  this.push(" ");
+
+  var spaces = node.operator === "in" || node.operator === "instanceof";
+  spaces = true; // todo: https://github.com/babel/babel/issues/1835
+  this.space(spaces);
+
   this.push(node.operator);
-  this.push(" ");
+
+  if (!spaces) {
+    // space is mandatory to avoid outputting <!--
+    // http://javascript.spec.whatwg.org/#comment-syntax
+    spaces = node.operator === "<" &&
+             t.isUnaryExpression(node.right, { prefix: true, operator: "!" }) &&
+             t.isUnaryExpression(node.right.argument, { prefix: true, operator: "--" });
+  }
+
+  this.space(spaces);
+
   print.plain(node.right);
 }
 
+/**
+ * Prints BindExpression, prints object and callee.
+ */
+
 export function BindExpression(node, print) {
   print.plain(node.object);
   this.push("::");
   print.plain(node.callee);
 }
 
+/**
+ * Alias ClassDeclaration printer as ClassExpression,
+ * and AssignmentExpression printer as LogicalExpression.
+ */
+
 export {
   AssignmentExpression as BinaryExpression,
   AssignmentExpression as LogicalExpression
 };
 
+/**
+ * Print MemberExpression, prints object, property, and value. Handles computed.
+ */
+
 export function MemberExpression(node, print) {
   var obj = node.object;
   print.plain(obj);
@@ -181,6 +274,10 @@ export function MemberExpression(node, print) {
   }
 }
 
+/**
+ * Print MetaProperty, prints meta and property.
+ */
+
 export function MetaProperty(node, print) {
   print.plain(node.meta);
   this.push(".");

src/babel/generation/generators/flow.js

@@ -1,24 +1,44 @@
 import * as t from "../../types";
 
+/**
+ * Prints AnyTypeAnnotation.
+ */
+
 export function AnyTypeAnnotation() {
   this.push("any");
 }
 
+/**
+ * Prints ArrayTypeAnnotation, prints elementType.
+ */
+
 export function ArrayTypeAnnotation(node, print) {
   print.plain(node.elementType);
   this.push("[");
   this.push("]");
 }
 
+/**
+ * Prints BooleanTypeAnnotation.
+ */
+
 export function BooleanTypeAnnotation(node) {
   this.push("bool");
 }
 
+/**
+ * Prints DeclareClass, prints node.
+ */
+
 export function DeclareClass(node, print) {
   this.push("declare class ");
   this._interfaceish(node, print);
 }
 
+/**
+ * Prints DeclareFunction, prints id and id.typeAnnotation.
+ */
+
 export function DeclareFunction(node, print) {
   this.push("declare function ");
   print.plain(node.id);
@@ -26,6 +46,10 @@ export function DeclareFunction(node, print) {
   this.semicolon();
 }
 
+/**
+ * Prints DeclareModule, prints id and body.
+ */
+
 export function DeclareModule(node, print) {
   this.push("declare module ");
   print.plain(node.id);
@@ -33,6 +57,10 @@ export function DeclareModule(node, print) {
   print.plain(node.body);
 }
 
+/**
+ * Prints DeclareVariable, prints id and id.typeAnnotation.
+ */
+
 export function DeclareVariable(node, print) {
   this.push("declare var ");
   print.plain(node.id);
@@ -40,6 +68,10 @@ export function DeclareVariable(node, print) {
   this.semicolon();
 }
 
+/**
+ * Prints FunctionTypeAnnotation, prints typeParameters, params, and rest.
+ */
+
 export function FunctionTypeAnnotation(node, print, parent) {
   print.plain(node.typeParameters);
   this.push("(");
@@ -68,6 +100,10 @@ export function FunctionTypeAnnotation(node, print, parent) {
   print.plain(node.returnType);
 }
 
+/**
+ * Prints FunctionTypeParam, prints name and typeAnnotation, handles optional.
+ */
+
 export function FunctionTypeParam(node, print) {
   print.plain(node.name);
   if (node.optional) this.push("?");
@@ -76,13 +112,26 @@ export function FunctionTypeParam(node, print) {
   print.plain(node.typeAnnotation);
 }
 
+/**
+ * Prints InterfaceExtends, prints id and typeParameters.
+ */
+
 export function InterfaceExtends(node, print) {
   print.plain(node.id);
   print.plain(node.typeParameters);
 }
 
+/**
+ * Alias InterfaceExtends printer as ClassImplements,
+ * and InterfaceExtends printer as GenericTypeAnnotation.
+ */
+
 export { InterfaceExtends as ClassImplements, InterfaceExtends as GenericTypeAnnotation };
 
+/**
+ * Prints interface-like node, prints id, typeParameters, extends, and body.
+ */
+
 export function _interfaceish(node, print) {
   print.plain(node.id);
   print.plain(node.typeParameters);
@@ -94,47 +143,87 @@ export function _interfaceish(node, print) {
   print.plain(node.body);
 }
 
+/**
+ * Prints InterfaceDeclaration, prints node.
+ */
+
 export function InterfaceDeclaration(node, print) {
   this.push("interface ");
   this._interfaceish(node, print);
 }
 
+/**
+ * Prints IntersectionTypeAnnotation, prints types.
+ */
+
 export function IntersectionTypeAnnotation(node, print) {
   print.join(node.types, { separator: " & " });
 }
 
+/**
+ * Prints MixedTypeAnnotation.
+ */
+
 export function MixedTypeAnnotation() {
   this.push("mixed");
 }
 
+/**
+ * Prints NullableTypeAnnotation, prints typeAnnotation.
+ */
+
 export function NullableTypeAnnotation(node, print) {
   this.push("?");
   print.plain(node.typeAnnotation);
 }
 
+/**
+ * Prints NumberTypeAnnotation.
+ */
+
 export function NumberTypeAnnotation() {
   this.push("number");
 }
 
+/**
+ * Prints StringLiteralTypeAnnotation, prints value.
+ */
+
 export function StringLiteralTypeAnnotation(node) {
   this._stringLiteral(node.value);
 }
 
+/**
+ * Prints StringTypeAnnotation.
+ */
+
 export function StringTypeAnnotation() {
   this.push("string");
 }
 
+/**
+ * Prints TupleTypeAnnotation, prints types.
+ */
+
 export function TupleTypeAnnotation(node, print) {
   this.push("[");
   print.join(node.types, { separator: ", " });
   this.push("]");
 }
 
+/**
+ * Prints TypeofTypeAnnotation, prints argument.
+ */
+
 export function TypeofTypeAnnotation(node, print) {
   this.push("typeof ");
   print.plain(node.argument);
 }
 
+/**
+ * Prints TypeAlias, prints id, typeParameters, and right.
+ */
+
 export function TypeAlias(node, print) {
   this.push("type ");
   print.plain(node.id);
@@ -146,6 +235,10 @@ export function TypeAlias(node, print) {
   this.semicolon();
 }
 
+/**
+ * Prints TypeAnnotation, prints typeAnnotation, handles optional.
+ */
+
 export function TypeAnnotation(node, print) {
   this.push(":");
   this.space();
@@ -153,14 +246,26 @@ export function TypeAnnotation(node, print) {
   print.plain(node.typeAnnotation);
 }
 
+/**
+ * Prints TypeParameterInstantiation, prints params.
+ */
+
 export function TypeParameterInstantiation(node, print) {
   this.push("<");
   print.join(node.params, { separator: ", " });
   this.push(">");
 }
 
+/**
+ * Alias TypeParameterInstantiation printer as TypeParameterDeclaration
+ */
+
 export { TypeParameterInstantiation as TypeParameterDeclaration };
 
+/**
+ * Prints ObjectTypeAnnotation, prints properties, callProperties, and indexers.
+ */
+
 export function ObjectTypeAnnotation(node, print) {
   this.push("{");
   var props = node.properties.concat(node.callProperties, node.indexers);
@@ -185,11 +290,19 @@ export function ObjectTypeAnnotation(node, print) {
   this.push("}");
 }
 
+/**
+ * Prints ObjectTypeCallProperty, prints value, handles static.
+ */
+
 export function ObjectTypeCallProperty(node, print) {
   if (node.static) this.push("static ");
   print.plain(node.value);
 }
 
+/**
+ * Prints ObjectTypeIndexer, prints id, key, and value, handles static.
+ */
+
 export function ObjectTypeIndexer(node, print) {
   if (node.static) this.push("static ");
   this.push("[");
@@ -203,6 +316,10 @@ export function ObjectTypeIndexer(node, print) {
   print.plain(node.value);
 }
 
+/**
+ * Prints ObjectTypeProperty, prints static, key, and value.
+ */
+
 export function ObjectTypeProperty(node, print) {
   if (node.static) this.push("static ");
   print.plain(node.key);
@@ -214,16 +331,28 @@ export function ObjectTypeProperty(node, print) {
   print.plain(node.value);
 }
 
+/**
+ * Prints QualifiedTypeIdentifier, prints qualification and id.
+ */
+
 export function QualifiedTypeIdentifier(node, print) {
   print.plain(node.qualification);
   this.push(".");
   print.plain(node.id);
 }
 
+/**
+ * Prints UnionTypeAnnotation, prints types.
+ */
+
 export function UnionTypeAnnotation(node, print) {
   print.join(node.types, { separator: " | " });
 }
 
+/**
+ * Prints TypeCastExpression, prints expression and typeAnnotation.
+ */
+
 export function TypeCastExpression(node, print) {
   this.push("(");
   print.plain(node.expression);
@@ -231,6 +360,10 @@ export function TypeCastExpression(node, print) {
   this.push(")");
 }
 
+/**
+ * Prints VoidTypeAnnotation.
+ */
+
 export function VoidTypeAnnotation(node) {
   this.push("void");
 }

src/babel/generation/generators/jsx.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * Prints JSXAttribute, prints name and value.
+ */
+
 export function JSXAttribute(node, print) {
   print.plain(node.name);
   if (node.value) {
@@ -8,34 +12,58 @@ export function JSXAttribute(node, print) {
   }
 }
 
+/**
+ * Prints JSXIdentifier, prints name.
+ */
+
 export function JSXIdentifier(node) {
   this.push(node.name);
 }
 
+/**
+ * Prints JSXNamespacedName, prints namespace and name.
+ */
+
 export function JSXNamespacedName(node, print) {
   print.plain(node.namespace);
   this.push(":");
   print.plain(node.name);
 }
 
+/**
+ * Prints JSXMemberExpression, prints object and property.
+ */
+
 export function JSXMemberExpression(node, print) {
   print.plain(node.object);
   this.push(".");
   print.plain(node.property);
 }
 
+/**
+ * Prints JSXSpreadAttribute, prints argument.
+ */
+
 export function JSXSpreadAttribute(node, print) {
   this.push("{...");
   print.plain(node.argument);
   this.push("}");
 }
 
+/**
+ * Prints JSXExpressionContainer, prints expression.
+ */
+
 export function JSXExpressionContainer(node, print) {
   this.push("{");
   print.plain(node.expression);
   this.push("}");
 }
 
+/**
+ * Prints JSXElement, prints openingElement, children, and closingElement.
+ */
+
 export function JSXElement(node, print) {
   var open = node.openingElement;
   print.plain(open);
@@ -54,6 +82,10 @@ export function JSXElement(node, print) {
   print.plain(node.closingElement);
 }
 
+/**
+ * Prints JSXOpeningElement, prints name and attributes, handles selfClosing.
+ */
+
 export function JSXOpeningElement(node, print) {
   this.push("<");
   print.plain(node.name);
@@ -64,10 +96,18 @@ export function JSXOpeningElement(node, print) {
   this.push(node.selfClosing ? " />" : ">");
 }
 
+/**
+ * Prints JSXClosingElement, prints name.
+ */
+
 export function JSXClosingElement(node, print) {
   this.push("</");
   print.plain(node.name);
   this.push(">");
 }
 
+/**
+ * Prints JSXEmptyExpression.
+ */
+
 export function JSXEmptyExpression() {}

src/babel/generation/generators/methods.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * Prints nodes with params, prints typeParameters, params, and returnType, handles optional params.
+ */
+
 export function _params(node, print) {
   print.plain(node.typeParameters);
   this.push("(");
@@ -16,6 +20,10 @@ export function _params(node, print) {
   }
 }
 
+/**
+ * Prints method-like nodes, prints key, value, and body, handles async, generator, computed, and get or set.
+ */
+
 export function _method(node, print) {
   var value = node.value;
   var kind  = node.kind;
@@ -42,10 +50,14 @@ export function _method(node, print) {
   }
 
   this._params(value, print);
-  this.push(" ");
+  this.space();
   print.plain(value.body);
 }
 
+/**
+ * Prints FunctionExpression, prints id and body, handles async and generator.
+ */
+
 export function FunctionExpression(node, print) {
   if (node.async) this.push("async ");
   this.push("function");
@@ -63,8 +75,17 @@ export function FunctionExpression(node, print) {
   print.plain(node.body);
 }
 
+/**
+ * Alias FunctionExpression printer as FunctionDeclaration.
+ */
+
 export { FunctionExpression as FunctionDeclaration };
 
+/**
+ * Prints ArrowFunctionExpression, prints params and body, handles async.
+ * Leaves out parentheses when single param.
+ */
+
 export function ArrowFunctionExpression(node, print) {
   if (node.async) this.push("async ");
 

src/babel/generation/generators/modules.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * Prints ImportSpecifier, prints imported and local.
+ */
+
 export function ImportSpecifier(node, print) {
   print.plain(node.imported);
   if (node.local && node.local.name !== node.imported.name) {
@@ -8,14 +12,26 @@ export function ImportSpecifier(node, print) {
   }
 }
 
+/**
+ * Prints ImportDefaultSpecifier, prints local.
+ */
+
 export function ImportDefaultSpecifier(node, print) {
   print.plain(node.local);
 }
 
+/**
+ * Prints ExportDefaultSpecifier, prints exported.
+ */
+
 export function ExportDefaultSpecifier(node, print) {
   print.plain(node.exported);
 }
 
+/**
+ * Prints ExportSpecifier, prints local and exported.
+ */
+
 export function ExportSpecifier(node, print) {
   print.plain(node.local);
   if (node.exported && node.local.name !== node.exported.name) {
@@ -24,11 +40,19 @@ export function ExportSpecifier(node, print) {
   }
 }
 
+/**
+ * Prints ExportNamespaceSpecifier, prints exported.
+ */
+
 export function ExportNamespaceSpecifier(node, print) {
   this.push("* as ");
   print.plain(node.exported);
 }
 
+/**
+ * Prints ExportAllDeclaration, prints exported and source.
+ */
+
 export function ExportAllDeclaration(node, print) {
   this.push("export *");
   if (node.exported) {
@@ -40,16 +64,28 @@ export function ExportAllDeclaration(node, print) {
   this.semicolon();
 }
 
+/**
+ * Prints ExportNamedDeclaration, delegates to ExportDeclaration.
+ */
+
 export function ExportNamedDeclaration(node, print) {
   this.push("export ");
   ExportDeclaration.call(this, node, print);
 }
 
+/**
+ * Prints ExportDefaultDeclaration, delegates to ExportDeclaration.
+ */
+
 export function ExportDefaultDeclaration(node, print) {
   this.push("export default ");
   ExportDeclaration.call(this, node, print);
 }
 
+/**
+ * Prints ExportDeclaration, prints specifiers, declration, and source.
+ */
+
 function ExportDeclaration(node, print) {
   var specifiers = node.specifiers;
 
@@ -87,11 +123,15 @@ function ExportDeclaration(node, print) {
   this.ensureSemicolon();
 }
 
+/**
+ * Prints ImportDeclaration, prints specifiers and source, handles isType.
+ */
+
 export function ImportDeclaration(node, print) {
   this.push("import ");
 
-  if (node.isType) {
-    this.push("type ");
+  if (node.importKind === "type" || node.importKind === "typeof") {
+    this.push(node.importKind + " ");
   }
 
   var specfiers = node.specifiers;
@@ -119,6 +159,10 @@ export function ImportDeclaration(node, print) {
   this.semicolon();
 }
 
+/**
+ * Prints ImportNamespaceSpecifier, prints local.
+ */
+
 export function ImportNamespaceSpecifier(node, print) {
   this.push("* as ");
   print.plain(node.local);

src/babel/generation/generators/statements.js

@@ -1,6 +1,10 @@
 import repeating from "repeating";
 import * as t from "../../types";
 
+/**
+ * Prints WithStatement, prints object and body.
+ */
+
 export function WithStatement(node, print) {
   this.keyword("with");
   this.push("(");
@@ -9,6 +13,10 @@ export function WithStatement(node, print) {
   print.block(node.body);
 }
 
+/**
+ * Prints IfStatement, prints test, consequent, and alternate.
+ */
+
 export function IfStatement(node, print) {
   this.keyword("if");
   this.push("(");
@@ -25,6 +33,10 @@ export function IfStatement(node, print) {
   }
 }
 
+/**
+ * Prints ForStatement, prints init, test, update, and body.
+ */
+
 export function ForStatement(node, print) {
   this.keyword("for");
   this.push("(");
@@ -47,6 +59,10 @@ export function ForStatement(node, print) {
   print.block(node.body);
 }
 
+/**
+ * Prints WhileStatement, prints test and body.
+ */
+
 export function WhileStatement(node, print) {
   this.keyword("while");
   this.push("(");
@@ -55,6 +71,11 @@ export function WhileStatement(node, print) {
   print.block(node.body);
 }
 
+/**
+ * Builds ForIn or ForOf statement printers.
+ * Prints left, right, and body.
+ */
+
 var buildForXStatement = function (op) {
   return function (node, print) {
     this.keyword("for");
@@ -67,9 +88,17 @@ var buildForXStatement = function (op) {
   };
 };
 
+/**
+ * Create ForInStatement and ForOfStatement printers.
+ */
+
 export var ForInStatement = buildForXStatement("in");
 export var ForOfStatement = buildForXStatement("of");
 
+/**
+ * Prints DoWhileStatement, prints body and test.
+ */
+
 export function DoWhileStatement(node, print) {
   this.push("do ");
   print.plain(node.body);
@@ -80,6 +109,11 @@ export function DoWhileStatement(node, print) {
   this.push(");");
 }
 
+/**
+ * Builds continue, return, or break statement printers.
+ * Prints label (or key).
+ */
+
 var buildLabelStatement = function (prefix, key) {
   return function (node, print) {
     this.push(prefix);
@@ -94,16 +128,28 @@ var buildLabelStatement = function (prefix, key) {
   };
 };
 
+/**
+ * Create ContinueStatement, ReturnStatement, and BreakStatement printers.
+ */
+
 export var ContinueStatement = buildLabelStatement("continue");
 export var ReturnStatement   = buildLabelStatement("return", "argument");
 export var BreakStatement    = buildLabelStatement("break");
 
+/**
+ * Prints LabeledStatement, prints label and body.
+ */
+
 export function LabeledStatement(node, print) {
   print.plain(node.label);
   this.push(": ");
   print.plain(node.body);
 }
 
+/**
+ * Prints TryStatement, prints block, handlers, and finalizer.
+ */
+
 export function TryStatement(node, print) {
   this.keyword("try");
   print.plain(node.block);
@@ -125,6 +171,10 @@ export function TryStatement(node, print) {
   }
 }
 
+/**
+ * Prints CatchClause, prints param and body.
+ */
+
 export function CatchClause(node, print) {
   this.keyword("catch");
   this.push("(");
@@ -133,12 +183,20 @@ export function CatchClause(node, print) {
   print.plain(node.body);
 }
 
+/**
+ * Prints ThrowStatement, prints argument.
+ */
+
 export function ThrowStatement(node, print) {
   this.push("throw ");
   print.plain(node.argument);
   this.semicolon();
 }
 
+/**
+ * Prints SwitchStatement, prints discriminant and cases.
+ */
+
 export function SwitchStatement(node, print) {
   this.keyword("switch");
   this.push("(");
@@ -157,6 +215,10 @@ export function SwitchStatement(node, print) {
   this.push("}");
 }
 
+/**
+ * Prints SwitchCase, prints test and consequent.
+ */
+
 export function SwitchCase(node, print) {
   if (node.test) {
     this.push("case ");
@@ -172,10 +234,18 @@ export function SwitchCase(node, print) {
   }
 }
 
+/**
+ * Prints DebuggerStatement.
+ */
+
 export function DebuggerStatement() {
   this.push("debugger;");
 }
 
+/**
+ * Prints VariableDeclaration, prints declarations, handles kind and format.
+ */
+
 export function VariableDeclaration(node, print, parent) {
   this.push(node.kind + " ");
 
@@ -190,22 +260,39 @@ export function VariableDeclaration(node, print, parent) {
     }
   }
 
-  var sep = ",";
+  //
+  // use a pretty separator when we aren't in compact mode, have initializers and don't have retainLines on
+  // this will format declarations like:
+  //
+  //   var foo = "bar", bar = "foo";
+  //
+  // into
+  //
+  //   var foo = "bar",
+  //       bar = "foo";
+  //
+
+  var sep;
   if (!this.format.compact && !this.format.concise && hasInits && !this.format.retainLines) {
-    sep += `\n${repeating(" ", node.kind.length + 1)}`;
-  } else {
-    sep += " ";
+    sep = `,\n${repeating(" ", node.kind.length + 1)}`;
   }
 
+  //
+
   print.list(node.declarations, { separator: sep });
 
   if (t.isFor(parent)) {
+    // don't give semicolons to these nodes since they'll be inserted in the parent generator
     if (parent.left === node || parent.init === node) return;
   }
 
   this.semicolon();
 }
 
+/**
+ * Prints VariableDeclarator, handles id, id.typeAnnotation, and init.
+ */
+
 export function VariableDeclarator(node, print) {
   print.plain(node.id);
   print.plain(node.id.typeAnnotation);

src/babel/generation/generators/template-literals.js

@@ -1,12 +1,24 @@
+/**
+ * Prints TaggedTemplateExpression, prints tag and quasi.
+ */
+
 export function TaggedTemplateExpression(node, print) {
   print.plain(node.tag);
   print.plain(node.quasi);
 }
 
+/**
+ * Prints TemplateElement, prints value.
+ */
+
 export function TemplateElement(node) {
   this._push(node.value.raw);
 }
 
+/**
+ * Prints TemplateLiteral, prints quasis, and expressions.
+ */
+
 export function TemplateLiteral(node, print) {
   this.push("`");
 

src/babel/generation/generators/types.js

@@ -3,17 +3,34 @@
 import isInteger from "is-integer";
 import * as t from "../../types";
 
+/**
+ * Prints Identifier, prints name.
+ */
+
 export function Identifier(node) {
   this.push(node.name);
 }
 
+/**
+ * Prints RestElement, prints argument.
+ */
+
 export function RestElement(node, print) {
   this.push("...");
   print.plain(node.argument);
 }
 
+/**
+ * Alias RestElement printer as SpreadElement,
+ * and RestElement printer as SpreadProperty.
+ */
+
 export { RestElement as SpreadElement, RestElement as SpreadProperty };
 
+/**
+ * Prints ObjectExpression, prints properties.
+ */
+
 export function ObjectExpression(node, print) {
   var props = node.properties;
 
@@ -30,9 +47,19 @@ export function ObjectExpression(node, print) {
   }
 }
 
+/**
+ * Alias ObjectExpression printer as ObjectPattern.
+ */
+
 export { ObjectExpression as ObjectPattern };
 
+/**
+ * Prints Property, prints decorators, key, and value, handles kind, computed, and shorthand.
+ */
+
 export function Property(node, print) {
+  print.list(node.decorators, { separator: "" });
+
   if (node.method || node.kind === "get" || node.kind === "set") {
     this._method(node, print);
   } else {
@@ -64,6 +91,10 @@ export function Property(node, print) {
   }
 }
 
+/**
+ * Prints ArrayExpression, prints elements.
+ */
+
 export function ArrayExpression(node, print) {
   var elems = node.elements;
   var len   = elems.length;
@@ -80,7 +111,7 @@ export function ArrayExpression(node, print) {
       // both (all) of the holes.
       this.push(",");
     } else {
-      if (i > 0) this.push(" ");
+      if (i > 0) this.space();
       print.plain(elem);
       if (i < len - 1) this.push(",");
     }
@@ -89,10 +120,22 @@ export function ArrayExpression(node, print) {
   this.push("]");
 }
 
+/**
+ * Alias ArrayExpression printer as ArrayPattern.
+ */
+
 export { ArrayExpression as ArrayPattern };
 
+/**
+ * RegExp for testing scientific notation in literals.
+ */
+
 const SCIENTIFIC_NOTATION = /e/i;
 
+/**
+ * Prints Literal, prints value, regex, raw, handles val type.
+ */
+
 export function Literal(node, print, parent) {
   var val  = node.value;
   var type = typeof val;
@@ -123,6 +166,10 @@ export function Literal(node, print, parent) {
   }
 }
 
+/**
+ * Prints string literals, handles format.
+ */
+
 export function _stringLiteral(val) {
   val = JSON.stringify(val);
 

src/babel/generation/index.js

@@ -11,6 +11,11 @@ import each from "lodash/collection/each";
 import n from "./node";
 import * as t from "../types";
 
+/**
+ * Babel's code generator, turns an ast into code, maintaining sourcemaps,
+ * user preferences, and valid output.
+ */
+
 class CodeGenerator {
   constructor(ast, opts, code) {
     opts = opts || {};
@@ -27,6 +32,13 @@ class CodeGenerator {
     this.buffer     = new Buffer(this.position, this.format);
   }
 
+  /**
+   * Normalize generator options, setting defaults.
+   *
+   * - Detects code indentation.
+   * - If `opts.compact = "auto"` and the code is over 100KB, `compact` will be set to `true`.
+   */
+
   static normalizeOptions(code, opts, tokens) {
     var style = "  ";
     if (code) {
@@ -57,6 +69,9 @@ class CodeGenerator {
     return format;
   }
 
+  /**
+   * Determine if input code uses more single or double quotes.
+   */
   static findCommonStringDelimiter(code, tokens) {
     var occurences = {
       single: 0,
@@ -79,7 +94,6 @@ class CodeGenerator {
       checked++;
       if (checked >= 3) break;
     }
-
     if (occurences.single > occurences.double) {
       return "single";
     } else {
@@ -87,6 +101,10 @@ class CodeGenerator {
     }
   }
 
+  /**
+   * All node generators.
+   */
+
   static generators = {
     templateLiterals: require("./generators/template-literals"),
     comprehensions:   require("./generators/comprehensions"),
@@ -101,6 +119,12 @@ class CodeGenerator {
     jsx:              require("./generators/jsx")
   };
 
+  /**
+   * Generate code and sourcemap from ast.
+   *
+   * Appends comments that weren't attached to any node to the end of the generated output.
+   */
+
   generate() {
     var ast = this.ast;
 
@@ -120,16 +144,23 @@ class CodeGenerator {
     };
   }
 
+  /**
+   * Build NodePrinter.
+   */
+
   buildPrint(parent) {
     return new NodePrinter(this, parent);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   catchUp(node, parent, leftParenPrinted) {
     // catch up to this nodes newline if we're behind
     if (node.loc && this.format.retainLines && this.buffer.buf) {
       var needsParens = false;
-      if (!leftParenPrinted && parent &&
-          this.position.line < node.loc.start.line && t.isTerminatorless(parent)) {
+      if (!leftParenPrinted && parent && this.position.line < node.loc.start.line && t.isTerminatorless(parent)) {
         needsParens = true;
         this._push("(");
       }
@@ -141,6 +172,10 @@ class CodeGenerator {
     return false;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _printNewline(leading, node, parent, opts) {
     if (!opts.statement && !n.isUserWhitespacable(node, parent)) {
       return;
@@ -171,6 +206,10 @@ class CodeGenerator {
     this.newline(lines);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   print(node, parent, opts = {}) {
     if (!node) return;
 
@@ -220,6 +259,10 @@ class CodeGenerator {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   printJoin(print, nodes, opts = {}) {
     if (!nodes || !nodes.length) return;
 
@@ -249,6 +292,10 @@ class CodeGenerator {
     if (opts.indent) this.dedent();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   printAndIndentOnComments(print, node) {
     var indent = !!node.leadingComments;
     if (indent) this.indent();
@@ -256,6 +303,10 @@ class CodeGenerator {
     if (indent) this.dedent();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   printBlock(print, node) {
     if (t.isEmptyStatement(node)) {
       this.semicolon();
@@ -265,6 +316,10 @@ class CodeGenerator {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   generateComment(comment) {
     var val = comment.value;
     if (comment.type === "CommentLine") {
@@ -275,14 +330,26 @@ class CodeGenerator {
     return val;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   printTrailingComments(node, parent) {
     this._printComments(this.getComments("trailingComments", node, parent));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   printLeadingComments(node, parent) {
     this._printComments(this.getComments("leadingComments", node, parent));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getComments(key, node, parent) {
     if (t.isExpressionStatement(parent)) {
       return [];
@@ -302,10 +369,18 @@ class CodeGenerator {
     return comments;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _getComments(key, node) {
     return (node && node[key]) || [];
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _printComments(comments) {
     if (this.format.compact) return;
     if (!this.format.comments) return;
@@ -373,16 +448,28 @@ class CodeGenerator {
   }
 }
 
+/**
+ * [Please add a description.]
+ */
+
 each(Buffer.prototype, function (fn, key) {
   CodeGenerator.prototype[key] = function () {
     return fn.apply(this.buffer, arguments);
   };
 });
 
+/**
+ * [Please add a description.]
+ */
+
 each(CodeGenerator.generators, function (generator) {
   extend(CodeGenerator.prototype, generator);
 });
 
+/**
+ * [Please add a description.]
+ */
+
 module.exports = function (ast, opts, code) {
   var gen = new CodeGenerator(ast, opts, code);
   return gen.generate();

src/babel/generation/node/index.js

@@ -4,6 +4,16 @@ import each from "lodash/collection/each";
 import some from "lodash/collection/some";
 import * as t from "../../types";
 
+/**
+ * Test if node matches a set of type-matcher pairs.
+ * @example
+ * find({
+ *   VariableDeclaration(node, parent) {
+ *     return true;
+ *   }
+ * }, node, parent);
+ */
+
 var find = function (obj, node, parent) {
   if (!obj) return;
   var result;
@@ -22,16 +32,28 @@ var find = function (obj, node, parent) {
   return result;
 };
 
+/**
+ * Whitespace and Parenthesis related methods for nodes.
+ */
+
 export default class Node {
   constructor(node, parent) {
     this.parent = parent;
     this.node   = node;
   }
 
+  /**
+   * Test if `node` can have whitespace set by the user.
+   */
+
   static isUserWhitespacable(node) {
     return t.isUserWhitespacable(node);
   }
 
+  /**
+   * Test if a `node` requires whitespace.
+   */
+
   static needsWhitespace(node, parent, type) {
     if (!node) return 0;
 
@@ -54,14 +76,26 @@ export default class Node {
     return (linesInfo && linesInfo[type]) || 0;
   }
 
+  /**
+   * Test if a `node` requires whitespace before it.
+   */
+
   static needsWhitespaceBefore(node, parent) {
     return Node.needsWhitespace(node, parent, "before");
   }
 
+  /**
+   * Test if a `note` requires whitespace after it.
+   */
+
   static needsWhitespaceAfter(node, parent) {
     return Node.needsWhitespace(node, parent, "after");
   }
 
+  /**
+   * Test if a `node` needs parentheses around it.
+   */
+
   static needsParens(node, parent) {
     if (!parent) return false;
 
@@ -77,6 +111,10 @@ export default class Node {
     return find(parens, node, parent);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   static needsParensNoLineTerminator(node, parent) {
     if (!parent) return false;
 
@@ -89,6 +127,10 @@ export default class Node {
   }
 }
 
+/**
+ * Add all static methods from `Node` to `Node.prototype`.
+ */
+
 each(Node, function (fn, key) {
   Node.prototype[key] = function () {
     // Avoid leaking arguments to prevent deoptimization

src/babel/generation/node/parentheses.js

@@ -1,6 +1,12 @@
 import each from "lodash/collection/each";
 import * as t from "../../types";
 
+/**
+ * Create a mapping of operators to precendence.
+ *
+ * @example
+ * { "==": 6, "+": 9 }
+ */
 const PRECEDENCE = {};
 
 each([
@@ -21,12 +27,24 @@ each([
   });
 });
 
+/**
+ * Test if NullableTypeAnnotation needs parentheses.
+ */
+
 export function NullableTypeAnnotation(node, parent) {
   return t.isArrayTypeAnnotation(parent);
 }
 
+/**
+ * Alias NullableTypeAnnotation test as FunctionTypeAnnotation.
+ */
+
 export { NullableTypeAnnotation as FunctionTypeAnnotation };
 
+/**
+ * Test if UpdateExpression needs parentheses.
+ */
+
 export function UpdateExpression(node, parent) {
   if (t.isMemberExpression(parent) && parent.object === node) {
     // (foo++).test()
@@ -34,6 +52,10 @@ export function UpdateExpression(node, parent) {
   }
 }
 
+/**
+ * Test if ObjectExpression needs parentheses.
+ */
+
 export function ObjectExpression(node, parent) {
   if (t.isExpressionStatement(parent)) {
     // ({ foo: "bar" });
@@ -48,6 +70,10 @@ export function ObjectExpression(node, parent) {
   return false;
 }
 
+/**
+ * Test if Binary needs parentheses.
+ */
+
 export function Binary(node, parent) {
   if ((t.isCallExpression(parent) || t.isNewExpression(parent)) && parent.callee === node) {
     return true;
@@ -78,6 +104,10 @@ export function Binary(node, parent) {
   }
 }
 
+/**
+ * Test if BinaryExpression needs parentheses.
+ */
+
 export function BinaryExpression(node, parent) {
   if (node.operator === "in") {
     // var i = (1 in []);
@@ -92,6 +122,10 @@ export function BinaryExpression(node, parent) {
   }
 }
 
+/**
+ * Test if SequenceExpression needs parentheses.
+ */
+
 export function SequenceExpression(node, parent) {
   if (t.isForStatement(parent)) {
     // Although parentheses wouldn't hurt around sequence
@@ -110,6 +144,10 @@ export function SequenceExpression(node, parent) {
   return true;
 }
 
+/**
+ * Test if YieldExpression needs parentheses.
+ */
+
 export function YieldExpression(node, parent) {
   return t.isBinary(parent) ||
          t.isUnaryLike(parent) ||
@@ -120,14 +158,26 @@ export function YieldExpression(node, parent) {
          t.isYieldExpression(parent);
 }
 
+/**
+ * Test if ClassExpression needs parentheses.
+ */
+
 export function ClassExpression(node, parent) {
   return t.isExpressionStatement(parent);
 }
 
+/**
+ * Test if UnaryLike needs parentheses.
+ */
+
 export function UnaryLike(node, parent) {
   return t.isMemberExpression(parent) && parent.object === node;
 }
 
+/**
+ * Test if FunctionExpression needs parentheses.
+ */
+
 export function FunctionExpression(node, parent) {
   // function () {};
   if (t.isExpressionStatement(parent)) {
@@ -145,6 +195,10 @@ export function FunctionExpression(node, parent) {
   }
 }
 
+/**
+ * Test if ConditionalExpression needs parentheses.
+ */
+
 export function ConditionalExpression(node, parent) {
   if (t.isUnaryLike(parent)) {
     return true;
@@ -171,6 +225,10 @@ export function ConditionalExpression(node, parent) {
   return false;
 }
 
+/**
+ * Test if AssignmentExpression needs parentheses.
+ */
+
 export function AssignmentExpression(node) {
   if (t.isObjectPattern(node.left)) {
     return true;

src/babel/generation/node/printer.js

@@ -1,31 +1,63 @@
+/**
+ * Printer for nodes, needs a `generator` and a `parent`.
+ */
+
 export default class NodePrinter {
   constructor(generator, parent) {
     this.generator = generator;
     this.parent = parent;
   }
 
+  /**
+   * Print a plain node.
+   */
+
   plain(node, opts) {
     return this.generator.print(node, this.parent, opts);
   }
 
+  /**
+   * Print a sequence of nodes as statements.
+   */
+
   sequence(nodes, opts = {}) {
     opts.statement = true;
     return this.generator.printJoin(this, nodes, opts);
   }
 
+  /**
+   * Print a sequence of nodes as expressions.
+   */
+
   join(nodes, opts) {
     return this.generator.printJoin(this, nodes, opts);
   }
 
+  /**
+   * Print a list of nodes, with a customizable separator (defaults to ",").
+   */
+
   list(items, opts = {}) {
-    if (opts.separator == null) opts.separator = ", ";
+    if (opts.separator == null) {
+      opts.separator = ",";
+      if (!this.generator.format.compact) opts.separator += " ";
+    }
+
     return this.join(items, opts);
   }
 
+  /**
+   * Print a block-like node.
+   */
+
   block(node) {
     return this.generator.printBlock(this, node);
   }
 
+  /**
+   * Print node and indent comments.
+   */
+
   indentOnComments(node) {
     return this.generator.printAndIndentOnComments(this, node);
   }

src/babel/generation/node/whitespace.js

@@ -3,6 +3,14 @@ import each from "lodash/collection/each";
 import map from "lodash/collection/map";
 import * as t from "../../types";
 
+/**
+ * Crawl a node to test if it contains a CallExpression, a Function, or a Helper.
+ *
+ * @example
+ * crawl(node)
+ * // { hasCall: false, hasFunction: true, hasHelper: false }
+ */
+
 function crawl(node, state = {}) {
   if (t.isMemberExpression(node)) {
     crawl(node.object, state);
@@ -22,6 +30,10 @@ function crawl(node, state = {}) {
   return state;
 }
 
+/**
+ * Test if a node is or has a helper.
+ */
+
 function isHelper(node) {
   if (t.isMemberExpression(node)) {
     return isHelper(node.object) || isHelper(node.property);
@@ -36,12 +48,25 @@ function isHelper(node) {
   }
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function isType(node) {
   return t.isLiteral(node) || t.isObjectExpression(node) || t.isArrayExpression(node) ||
          t.isIdentifier(node) || t.isMemberExpression(node);
 }
 
+/**
+ * Tests for node types that need whitespace.
+ */
+
 exports.nodes = {
+
+  /**
+   * Test if AssignmentExpression needs whitespace.
+   */
+
   AssignmentExpression(node) {
     var state = crawl(node.right);
     if ((state.hasCall && state.hasHelper) || state.hasFunction) {
@@ -52,12 +77,20 @@ exports.nodes = {
     }
   },
 
+  /**
+   * Test if SwitchCase needs whitespace.
+   */
+
   SwitchCase(node, parent) {
     return {
       before: node.consequent.length || parent.cases[0] === node
     };
   },
 
+  /**
+   * Test if LogicalExpression needs whitespace.
+   */
+
   LogicalExpression(node) {
     if (t.isFunction(node.left) || t.isFunction(node.right)) {
       return {
@@ -66,6 +99,10 @@ exports.nodes = {
     }
   },
 
+  /**
+   * Test if Literal needs whitespace.
+   */
+
   Literal(node) {
     if (node.value === "use strict") {
       return {
@@ -74,6 +111,10 @@ exports.nodes = {
     }
   },
 
+  /**
+   * Test if CallExpression needs whitespace.
+   */
+
   CallExpression(node) {
     if (t.isFunction(node.callee) || isHelper(node)) {
       return {
@@ -83,6 +124,10 @@ exports.nodes = {
     }
   },
 
+  /**
+   * Test if VariableDeclaration needs whitespace.
+   */
+
   VariableDeclaration(node) {
     for (var i = 0; i < node.declarations.length; i++) {
       var declar = node.declarations[i];
@@ -102,6 +147,10 @@ exports.nodes = {
     }
   },
 
+  /**
+   * Test if IfStatement needs whitespace.
+   */
+
   IfStatement(node) {
     if (t.isBlockStatement(node.consequent)) {
       return {
@@ -112,6 +161,10 @@ exports.nodes = {
   }
 };
 
+/**
+ * Test if Property or SpreadProperty needs whitespace.
+ */
+
 exports.nodes.Property =
 exports.nodes.SpreadProperty = function (node, parent) {
   if (parent.properties[0] === node) {
@@ -121,20 +174,41 @@ exports.nodes.SpreadProperty = function (node, parent) {
   }
 };
 
+/**
+ * Returns lists from node types that need whitespace.
+ */
+
 exports.list = {
+
+  /**
+   * Return VariableDeclaration declarations init properties.
+   */
+
   VariableDeclaration(node) {
     return map(node.declarations, "init");
   },
 
+  /**
+   * Return VariableDeclaration elements.
+   */
+
   ArrayExpression(node) {
     return node.elements;
   },
 
+  /**
+   * Return VariableDeclaration properties.
+   */
+
   ObjectExpression(node) {
     return node.properties;
   }
 };
 
+/**
+ * Add whitespace tests for nodes and their aliases.
+ */
+
 each({
   Function: true,
   Class: true,

src/babel/generation/position.js

@@ -1,9 +1,17 @@
+/**
+ * Track current position in code generation.
+ */
+
 export default class Position {
   constructor() {
     this.line = 1;
     this.column = 0;
   }
 
+  /**
+   * Push a string to the current position, mantaining the current line and column.
+   */
+
   push(str) {
     for (var i = 0; i < str.length; i++) {
       if (str[i] === "\n") {
@@ -15,6 +23,10 @@ export default class Position {
     }
   }
 
+  /**
+   * Unshift a string from the current position, mantaining the current line and column.
+   */
+
   unshift(str) {
     for (var i = 0; i < str.length; i++) {
       if (str[i] === "\n") {

src/babel/generation/source-map.js

@@ -1,6 +1,10 @@
 import sourceMap from "source-map";
 import * as t from "../types";
 
+/**
+ * Build a sourcemap.
+ */
+
 export default class SourceMap {
   constructor(position, opts, code) {
     this.position = position;
@@ -18,6 +22,10 @@ export default class SourceMap {
     }
   }
 
+  /**
+   * Get the sourcemap.
+   */
+
   get() {
     var map = this.map;
     if (map) {
@@ -27,6 +35,10 @@ export default class SourceMap {
     }
   }
 
+  /**
+   * Mark a node's generated position, and add it to the sourcemap.
+   */
+
   mark(node, type) {
     var loc = node.loc;
     if (!loc) return; // no location info

src/babel/generation/whitespace.js

@@ -18,6 +18,10 @@ function getLookupIndex(i, base, max) {
   return i;
 }
 
+/**
+ * Get whitespace around tokens.
+ */
+
 export default class Whitespace {
   constructor(tokens) {
     this.tokens = tokens;
@@ -34,6 +38,10 @@ export default class Whitespace {
     this._lastFoundIndex = 0;
   }
 
+  /**
+   * Count all the newlines before a node.
+   */
+
   getNewlinesBefore(node) {
     var startToken;
     var endToken;
@@ -57,6 +65,10 @@ export default class Whitespace {
     return this.getNewlinesBetween(startToken, endToken);
   }
 
+  /**
+   * Count all the newlines after a node.
+   */
+
   getNewlinesAfter(node) {
     var startToken;
     var endToken;
@@ -91,6 +103,10 @@ export default class Whitespace {
     }
   }
 
+  /**
+   * Count all the newlines between two tokens.
+   */
+
   getNewlinesBetween(startToken, endToken) {
     if (!endToken || !endToken.loc) return 0;
 

src/babel/helpers/README.md

@@ -0,0 +1,4 @@
+## Helpers
+
+Utilities for Babel, which is just another way to say "helpers", but I wrote it
+anyways, so– deal with it.

src/babel/helpers/code-frame.js

@@ -4,6 +4,10 @@ import jsTokens from "js-tokens";
 import esutils from "esutils";
 import chalk from "chalk";
 
+/**
+ * Chalk styles for token types.
+ */
+
 var defs = {
   string:     chalk.red,
   punctuator: chalk.bold,
@@ -17,8 +21,16 @@ var defs = {
   invalid:    chalk.inverse
 };
 
+/**
+ * RegExp to test for newlines in terminal.
+ */
+
 const NEWLINE = /\r\n|[\n\r\u2028\u2029]/;
 
+/**
+ * Get the type of token, specifying punctuator type.
+ */
+
 function getTokenType(match) {
   var token = jsTokens.matchToToken(match);
   if (token.type === "name" && esutils.keyword.isReservedWordES6(token.value)) {
@@ -42,6 +54,10 @@ function getTokenType(match) {
   return token.type;
 }
 
+/**
+ * Highlight `text`.
+ */
+
 function highlight(text) {
   return text.replace(jsTokens, function (...args) {
     var type = getTokenType(args);
@@ -54,6 +70,10 @@ function highlight(text) {
   });
 }
 
+/**
+ * Create a code frame, adding line numbers, code highlighting, and pointing to a given position.
+ */
+
 export default function (lines: number, lineNumber: number, colNumber: number, opts = {}): string {
   colNumber = Math.max(colNumber, 0);
 

src/babel/helpers/merge.js

@@ -1,10 +1,14 @@
 import merge from "lodash/object/merge";
 
+/**
+ * Merge options.
+ */
+
 export default function (dest, src) {
   if (!dest || !src) return;
 
-  return merge(dest, src, function(a, b) {
-    if (Array.isArray(a)) {
+  return merge(dest, src, function (a, b) {
+    if (b && Array.isArray(a)) {
       var c = a.slice(0);
       for (var v of b) {
         if (a.indexOf(v) < 0) {

src/babel/helpers/normalize-ast.js

@@ -1,5 +1,11 @@
 import * as t from "../types";
 
+/**
+ * Normalize an AST.
+ *
+ * - Wrap `Program` node with a `File` node.
+ */
+
 export default function (ast, comments, tokens) {
   if (ast && ast.type === "Program") {
     return t.file(ast, comments || [], tokens || []);

src/babel/helpers/object.js

@@ -1,3 +1,7 @@
+/**
+ * Create an object with a `null` prototype.
+ */
+
 export default function () {
   return Object.create(null);
 }

src/babel/helpers/parse.js

@@ -2,6 +2,10 @@ import normalizeAst from "./normalize-ast";
 import estraverse from "estraverse";
 import * as acorn from "../../acorn";
 
+/**
+ * Parse `code` with normalized options, collecting tokens and comments.
+ */
+
 export default function (code, opts = {}) {
   var commentsAndTokens = [];
   var comments          = [];
@@ -21,11 +25,17 @@ export default function (code, opts = {}) {
     ranges:                      true
   };
 
+  /**
+   * Collect all tokens.
+   */
   parseOpts.onToken = function (token) {
     tokens.push(token);
     commentsAndTokens.push(token);
   };
 
+  /**
+   * Collection all comments.
+   */
   parseOpts.onComment = function (block, text, start, end, startLoc, endLoc) {
     var comment = {
       type: block ? "CommentBlock" : "CommentLine",

src/babel/messages.js

@@ -1,7 +1,12 @@
 import * as util from  "util";
 
+/**
+ * Mapping of messages to be used in Babel.
+ * Messages can include $0-style placeholders.
+ */
+
 export const MESSAGES = {
-  tailCallReassignmentDeopt: "Function reference has been reassigned so it's probably be dereferenced so we can't optimise this with confidence",
+  tailCallReassignmentDeopt: "Function reference has been reassigned, so it will probably be dereferenced, therefore we can't optimise this with confidence",
   JSXNamespacedTags: "Namespace tags are not supported. ReactJSX is not XML.",
   classesIllegalBareSuper: "Illegal use of bare super",
   classesIllegalSuperCall: "Direct super call is illegal in non-constructor, use super.$1() instead",
@@ -17,7 +22,7 @@ export const MESSAGES = {
   missingTemplatesDirectory: "no templates directory - this is most likely the result of a broken `npm publish`. Please report to https://github.com/babel/babel/issues",
   unsupportedOutputType: "Unsupported output type $1",
   illegalMethodName: "Illegal method name $1",
-  lostTrackNodePath: "We lost track of this nodes position, likely because the AST was directly manipulated",
+  lostTrackNodePath: "We lost track of this node's position, likely because the AST was directly manipulated",
 
   modulesIllegalExportName: "Illegal export $1",
   modulesDuplicateDeclarations: "Duplicate module declarations with the same source but in different scopes",
@@ -26,7 +31,7 @@ export const MESSAGES = {
   undeclaredVariableType: "Referencing a type alias outside of a type annotation",
   undeclaredVariableSuggestion: "Reference to undeclared variable $1 - did you mean $2?",
 
-  traverseNeedsParent: "Must pass a scope and parentPath unless traversing a Program/File got a $1 node",
+  traverseNeedsParent: "You must pass a scope and parentPath unless traversing a Program/File got a $1 node",
   traverseVerifyRootFunction: "You passed `traverse()` a function when it expected a visitor object, are you sure you didn't mean `{ enter: Function }`?",
   traverseVerifyVisitorProperty: "You passed `traverse()` a visitor object with the property $1 that has the invalid property $2",
   traverseVerifyNodeType: "You gave us a visitor for the node type $1 but it's not a valid type",
@@ -37,21 +42,41 @@ export const MESSAGES = {
   pluginNotTransformer: "The plugin $1 didn't export a Plugin instance",
   pluginUnknown: "Unknown plugin $1",
 
-  pluginNotFile: "Plugin $1 is resolving to a different Babel version to what is doing the actual transformation..."
+  pluginNotFile: "Plugin $1 is resolving to a different Babel version than what is performing the transformation.",
+
+  pluginInvalidProperty: "Plugin $1 provided an invalid property of $2.",
+  pluginInvalidPropertyVisitor: `Define your visitor methods inside a \`visitor\` property like so:
+
+  new Plugin("foobar", {
+    visitor: {
+      // define your visitor methods here!
+    }
+  });
+`
 };
 
-export function get(key: String, ...args) {
+/**
+ * Get a message with $0 placeholders replaced by arguments.
+ */
+
+export function get(key: string, ...args): string {
   var msg = MESSAGES[key];
   if (!msg) throw new ReferenceError(`Unknown message ${JSON.stringify(key)}`);
 
+  // stringify args
   args = parseArgs(args);
 
+  // replace $0 placeholders with args
   return msg.replace(/\$(\d+)/g, function (str, i) {
     return args[--i];
   });
 }
 
-export function parseArgs(args: Array<any>) {
+/**
+ * Stingify arguments to be used inside messages.
+ */
+
+export function parseArgs(args: Array<any>): Array<string> {
   return args.map(function (val) {
     if (val != null && val.inspect) {
       return val.inspect();

src/babel/patch.js

@@ -1,83 +1,7 @@
 import estraverse from "estraverse";
 import extend from "lodash/object/extend";
-import types from "ast-types";
 import * as t from "./types";
 
 // estraverse
 
 extend(estraverse.VisitorKeys, t.VISITOR_KEYS);
-
-// regenerator/ast-types
-
-var def = types.Type.def;
-var or  = types.Type.or;
-
-//def("File")
-//  .bases("Node")
-//  .build("program")
-//  .field("program", def("Program"));
-
-def("Noop");
-
-def("AssignmentPattern")
-  .bases("Pattern")
-  .build("left", "right")
-  .field("left", def("Pattern"))
-  .field("right", def("Expression"));
-
-def("RestElement")
-  .bases("Pattern")
-  .build("argument")
-  .field("argument", def("expression"));
-
-def("DoExpression")
-  .bases("Expression")
-  .build("body")
-  .field("body", [def("Statement")]);
-
-def("Super")
-  .bases("Expression");
-
-def("ExportDefaultDeclaration")
-  .bases("Declaration")
-  .build("declaration")
-  .field("declaration", or(
-    def("Declaration"),
-    def("Expression"),
-    null
-  ));
-
-def("ExportNamedDeclaration")
-  .bases("Declaration")
-  .build("declaration")
-  .field("declaration", or(
-    def("Declaration"),
-    def("Expression"),
-    null
-  ))
-  .field("specifiers", [or(
-    def("ExportSpecifier")
-  )])
-  .field("source", or(def("ModuleSpecifier"), null));
-
-def("ExportNamespaceSpecifier")
-  .bases("Specifier")
-  .field("exported", def("Identifier"));
-
-def("ExportDefaultSpecifier")
-  .bases("Specifier")
-  .field("exported", def("Identifier"));
-
-def("ExportAllDeclaration")
-  .bases("Declaration")
-  .build("exported", "source")
-  .field("exported", def("Identifier"))
-  .field("source", def("Literal"));
-
-def("BindExpression")
-  .bases("Expression")
-  .build("object", "callee")
-  .field("object", or(def("Expression"), null))
-  .field("callee", def("Expression"));
-
-types.finalize();

src/babel/tools/README.md

@@ -0,0 +1,15 @@
+## Tools
+
+> This directory is best browsed while listening to
+> https://www.youtube.com/watch?v=hglVqACd1C8.
+
+### Protect Babel
+
+The protect script seen here is to throw errors if someone ever tries to
+include internal babel files in their script. If you need something to be
+exposed, you should ask for it, not try to hack your way into getting it.
+
+### External Helpers
+
+You'll also find the script for building the external helpers file, this is
+the Babel "runtime" where all helper functions go instead of the top of a file.

src/babel/tools/build-external-helpers.js

@@ -5,6 +5,10 @@ import File from "../transformation/file";
 import each from "lodash/collection/each";
 import * as t from "../types";
 
+/**
+ * [Please add a description.]
+ */
+
 function buildGlobal(namespace, builder) {
   var body      = [];
   var container = t.functionExpression(null, [t.identifier("global")], t.blockStatement(body));
@@ -22,6 +26,10 @@ function buildGlobal(namespace, builder) {
   return tree;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function buildUmd(namespace, builder) {
   var body = [];
   body.push(t.variableDeclaration("var", [
@@ -41,6 +49,10 @@ function buildUmd(namespace, builder) {
   return t.program([container]);
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function buildVar(namespace, builder) {
   var body = [];
   body.push(t.variableDeclaration("var", [
@@ -50,6 +62,10 @@ function buildVar(namespace, builder) {
   return t.program(body);
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function buildHelpers(body, namespace, whitelist) {
   each(File.helpers, function (name) {
     if (whitelist && whitelist.indexOf(name) === -1) return;
@@ -61,6 +77,10 @@ function buildHelpers(body, namespace, whitelist) {
   });
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (whitelist, outputType = "global") {
   var namespace = t.identifier("babelHelpers");
 

src/babel/tools/protect.js

@@ -0,0 +1,14 @@
+import path from "path";
+
+var root = path.resolve(__dirname, "../../../");
+
+/**
+ * Protect Babel internals from being hotlinked by other tools.
+ * Sorry, not sorry.
+ */
+
+export default function (module) {
+  if (module.parent && module.parent.filename.indexOf(root) !== 0) {
+    throw new Error("Don't hotlink internal Babel files.");
+  }
+}

src/babel/transformation/README.md

@@ -0,0 +1,3 @@
+## Transformation
+
+This is the Transformation directory.

src/babel/transformation/file/README.md

@@ -0,0 +1,3 @@
+## File Transformation
+
+This is the File Transformation directory.

src/babel/transformation/file/index.js

@@ -1,30 +1,28 @@
-import { validateOption, normaliseOptions, config as optionsConfig } from "./options";
 import convertSourceMap from "convert-source-map";
 import moduleFormatters from "../modules";
+import OptionManager from "./options/option-manager";
 import PluginManager from "./plugin-manager";
 import shebangRegex from "shebang-regex";
 import NodePath from "../../traversal/path";
 import isFunction from "lodash/lang/isFunction";
-import isAbsolute from "path-is-absolute";
-import resolveRc from "./options/resolve-rc";
 import sourceMap from "source-map";
 import generate from "../../generation";
 import codeFrame from "../../helpers/code-frame";
 import defaults from "lodash/object/defaults";
 import includes from "lodash/collection/includes";
 import traverse from "../../traversal";
-import assign from "lodash/object/assign";
 import Logger from "./logger";
 import Plugin from "../plugin";
 import parse from "../../helpers/parse";
-import merge from "../../helpers/merge";
-import slash from "slash";
-import clone from "lodash/lang/clone";
 import Hub from "../../traversal/hub";
 import * as util from  "../../util";
 import path from "path";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default class File {
   constructor(opts = {}, pipeline) {
     this.transformerDependencies = {};
@@ -50,15 +48,18 @@ export default class File {
 
     this.pipeline = pipeline;
     this.log      = new Logger(this, opts.filename || "unknown");
+    this.opts     = this.initOptions(opts);
     this.ast      = {};
 
-    this.normaliseOptions(opts);
-
     this.buildTransformers();
 
     this.hub = new Hub(this);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   static helpers = [
     "inherits",
     "defaults",
@@ -93,72 +94,27 @@ export default class File {
     "instanceof",
 
     // legacy
-    "interop-require",
+    "interop-require"
   ];
 
+  /**
+   * [Please add a description.]
+   */
+
   static soloHelpers = [];
 
-  static options = optionsConfig;
 
-  normaliseOptions(opts: Object) {
-    opts = this.opts = normaliseOptions(assign({}, opts));
+  /**
+   * [Please add a description.]
+   */
 
-    // resolve babelrc
-    if (opts.filename) {
-      var rcFilename = opts.filename;
-      if (!isAbsolute(rcFilename)) rcFilename = path.join(process.cwd(), rcFilename);
-      opts = resolveRc(rcFilename, opts);
-    }
-
-    // check for unknown options
-    for (let key in opts) {
-      if (key[0] === "_") continue;
-
-      let option = File.options[key];
-      if (!option) this.log.error(`Unknown option: ${key}`, ReferenceError);
-    }
-
-    // merge in environment options
-    var envKey = process.env.BABEL_ENV || process.env.NODE_ENV || "development";
-    if (opts.env) merge(opts, normaliseOptions(opts.env[envKey]));
-
-    // normalise options
-    for (let key in File.options) {
-      let option = File.options[key];
-      var val    = opts[key];
-
-      // optional
-      if (!val && option.optional) continue;
-
-      // deprecated
-      if (val && option.deprecated) {
-        this.log.deprecate("Deprecated option " + key + ": " + option.deprecated);
-      }
-
-      // default
-      if (val == null) val = clone(option.default);
-
-      // validate
-      if (val) val = validateOption(key, val, this.pipeline);
-
-      // aaliases
-      if (option.alias) {
-        opts[option.alias] = opts[option.alias] || val;
-      } else {
-        opts[key] = val;
-      }
-    }
+  initOptions(opts) {
+    opts = new OptionManager(this.log, this.pipeline).init(opts);
 
     if (opts.inputSourceMap) {
       opts.sourceMaps = true;
     }
 
-    // normalize windows path separators to unix
-    opts.filename = slash(opts.filename);
-    if (opts.sourceRoot) {
-      opts.sourceRoot = slash(opts.sourceRoot);
-    }
-
     if (opts.moduleId) {
       opts.moduleIds = true;
     }
@@ -167,9 +123,7 @@ export default class File {
 
     opts.ignore = util.arrayify(opts.ignore, util.regexify);
 
-    if (opts.only) {
-      opts.only = util.arrayify(opts.only, util.regexify);
-    }
+    if (opts.only) opts.only = util.arrayify(opts.only, util.regexify);
 
     defaults(opts, {
       moduleRoot: opts.sourceRoot
@@ -195,12 +149,20 @@ export default class File {
     }
 
     return opts;
-  };
+  }
+
+  /**
+   * [Please add a description.]
+   */
 
   isLoose(key: string) {
     return includes(this.opts.loose, key);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildTransformers() {
     var file = this;
 
@@ -255,6 +217,10 @@ export default class File {
     this.transformerStack = this.collapseStack(stack);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   collapseStack(_stack) {
     var stack  = [];
     var ignore = [];
@@ -291,14 +257,26 @@ export default class File {
     return stack;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   set(key: string, val): any {
     return this.data[key] = val;
-  };
+  }
+
+  /**
+   * [Please add a description.]
+   */
 
   setDynamic(key: string, fn: Function) {
     this.dynamicData[key] = fn;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   get(key: string): any {
     var data = this.data[key];
     if (data) {
@@ -311,12 +289,20 @@ export default class File {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   resolveModuleSource(source: string): string {
     var resolveModuleSource = this.opts.resolveModuleSource;
     if (resolveModuleSource) source = resolveModuleSource(source, this.opts.filename);
     return source;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addImport(source: string, name?: string, type?: string): Object {
     name = name || source;
     var id = this.dynamicImportIds[name];
@@ -345,6 +331,10 @@ export default class File {
     return id;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   attachAuxiliaryComment(node: Object): Object {
     var beforeComment = this.opts.auxiliaryCommentBefore;
     if (beforeComment) {
@@ -367,6 +357,10 @@ export default class File {
     return node;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addHelper(name: string): Object {
     var isSolo = includes(File.soloHelpers, name);
 
@@ -413,6 +407,10 @@ export default class File {
     return uid;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   errorWithNode(node, msg, Error = SyntaxError) {
     var err;
     if (node && node.loc) {
@@ -426,6 +424,10 @@ export default class File {
     return err;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   mergeSourceMap(map: Object) {
     var opts = this.opts;
 
@@ -448,6 +450,9 @@ export default class File {
     return map;
   }
 
+  /**
+   * [Please add a description.]
+   */
 
   getModuleFormatter(type: string) {
     if (isFunction(type) || !moduleFormatters[type]) {
@@ -468,6 +473,10 @@ export default class File {
     return new ModuleFormatter(this);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   parse(code: string) {
     var opts = this.opts;
 
@@ -496,6 +505,10 @@ export default class File {
     return tree;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _addAst(ast) {
     this.path = NodePath.get({
       hub: this.hub,
@@ -508,6 +521,10 @@ export default class File {
     this.ast   = ast;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addAst(ast) {
     this.log.debug("Start set AST");
     this._addAst(ast);
@@ -521,6 +538,10 @@ export default class File {
     this.log.debug("End module formatter init");
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   transform() {
     this.call("pre");
     for (var pass of (this.transformerStack: Array)) {
@@ -531,6 +552,10 @@ export default class File {
     return this.generate();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   wrap(code, callback) {
     code = code + "";
 
@@ -568,22 +593,38 @@ export default class File {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addCode(code: string) {
     code = (code || "") + "";
     code = this.parseInputSourceMap(code);
     this.code = code;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   parseCode() {
     this.parseShebang();
     this.addAst(this.parse(this.code));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   shouldIgnore() {
     var opts = this.opts;
     return util.shouldIgnore(opts.filename, opts.ignore, opts.only);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   call(key: string) {
     for (var pass of (this.uncollapsedTransformerStack: Array)) {
       var fn = pass.plugin[key];
@@ -591,6 +632,10 @@ export default class File {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   parseInputSourceMap(code: string) {
     var opts = this.opts;
 
@@ -605,6 +650,10 @@ export default class File {
     return code;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   parseShebang() {
     var shebangMatch = shebangRegex.exec(this.code);
     if (shebangMatch) {
@@ -613,6 +662,10 @@ export default class File {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   makeResult({ code, map = null, ast, ignored }) {
     var result = {
       metadata: null,
@@ -638,6 +691,10 @@ export default class File {
     return result;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   generate() {
     var opts = this.opts;
     var ast  = this.ast;

src/babel/transformation/file/logger.js

@@ -4,40 +4,82 @@ import buildDebug from "debug/node";
 var verboseDebug = buildDebug("babel:verbose");
 var generalDebug = buildDebug("babel");
 
+var seenDeprecatedMessages = [];
+
+/**
+ * [Please add a description.]
+ */
+
 export default class Logger {
   constructor(file: File, filename: string) {
     this.filename = filename;
     this.file     = file;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _buildMessage(msg: string): string {
     var parts = `[BABEL] ${this.filename}`;
     if (msg) parts += `: ${msg}`;
     return parts;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   warn(msg) {
     console.warn(this._buildMessage(msg));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   error(msg: string, Constructor = Error) {
     throw new Constructor(this._buildMessage(msg));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   deprecate(msg) {
-    if (!this.file.opts.suppressDeprecationMessages) {
-      console.error(this._buildMessage(msg));
-    }
+    if (this.file.opts.suppressDeprecationMessages) return;
+
+    msg = this._buildMessage(msg);
+
+    // already seen this message
+    if (seenDeprecatedMessages.indexOf(msg) >= 0) return;
+
+    // make sure we don't see it again
+    seenDeprecatedMessages.push(msg);
+
+    console.error(msg);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   verbose(msg: string) {
     if (verboseDebug.enabled) verboseDebug(this._buildMessage(msg));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   debug(msg: string) {
     if (generalDebug.enabled) generalDebug(this._buildMessage(msg));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   deopt(node: Object, msg: string) {
     this.debug(msg);
   }

src/babel/transformation/file/options/README.md

@@ -0,0 +1,3 @@
+## File Options
+
+This is the File Options directory.

src/babel/transformation/file/options/config.json

@@ -1,6 +1,6 @@
 {
   "filename": {
-    "type": "string",
+    "type": "filename",
     "description": "filename to use when reading from stdin - this will be used in source-maps, errors etc",
     "default": "unknown",
     "shorthand": "f"
@@ -236,12 +236,12 @@
   },
 
   "sourceRoot": {
-    "type": "string",
+    "type": "filename",
     "description": "the root from which all sources are relative"
   },
 
   "moduleRoot": {
-    "type": "string",
+    "type": "filename",
     "description": "optional prefix for the AMD module formatter that will be prepend to the filename on module definitions"
   },
 
@@ -253,7 +253,7 @@
   },
 
   "babelrc": {
-    "hidden": true,
-    "description": "do not load the same .babelrc file twice"
+    "description": "Specify a custom list of babelrc files to use",
+    "type": "list"
   }
 }

src/babel/transformation/file/options/index.js

@@ -3,6 +3,10 @@ import config from "./config";
 
 export { config };
 
+/**
+ * Validate an option.
+ */
+
 export function validateOption(key, val, pipeline) {
   var opt = config[key];
   var parser = opt && parsers[opt.type];
@@ -13,6 +17,10 @@ export function validateOption(key, val, pipeline) {
   }
 }
 
+/**
+ * Normalize all options.
+ */
+
 export function normaliseOptions(options = {}) {
   for (var key in options) {
     var val = options[key];

src/babel/transformation/file/options/option-manager.js

@@ -0,0 +1,170 @@
+import { validateOption, normaliseOptions } from "./index";
+import stripJsonComments from "strip-json-comments";
+import isAbsolute from "path-is-absolute";
+import pathExists from "path-exists";
+import clone from "lodash/lang/clone";
+import merge from "../../../helpers/merge";
+import config from "./config";
+import path from "path";
+import fs from "fs";
+
+var existsCache = {};
+var jsonCache   = {};
+
+const CONFIG_FILENAME = ".babelrc";
+
+function exists(filename) {
+  var cached = existsCache[filename];
+  if (cached != null) {
+    return cached;
+  } else {
+    return existsCache[filename] = pathExists.sync(filename);
+  }
+}
+
+export default class OptionManager {
+  constructor(log, pipeline) {
+    this.resolvedConfigs = [];
+    this.options         = OptionManager.createBareOptions();
+    this.pipeline        = pipeline;
+    this.log             = log;
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  static createBareOptions() {
+    var opts = {};
+
+    for (var key in config) {
+      var opt = config[key];
+      opts[key] = clone(opt.default);
+    }
+
+    return opts;
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  addConfig(loc) {
+    if (this.resolvedConfigs.indexOf(loc) >= 0) return;
+
+    var content = fs.readFileSync(loc, "utf8");
+    var opts;
+
+    try {
+      opts = jsonCache[content] = jsonCache[content] || JSON.parse(stripJsonComments(content));
+    } catch (err) {
+      err.message = `${loc}: ${err.message}`;
+      throw err;
+    }
+
+    this.mergeOptions(opts, loc);
+    this.resolvedConfigs.push(loc);
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  mergeOptions(opts, alias = "foreign") {
+    if (!opts) return;
+
+    for (let key in opts) {
+      if (key[0] === "_") continue;
+
+      let option = config[key];
+
+      // check for an unknown option
+      if (!option) this.log.error(`Unknown option: ${alias}.${key}`, ReferenceError);
+    }
+
+    // normalise options
+    normaliseOptions(opts);
+
+    // merge them into this current files options
+    merge(this.options, opts);
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  findConfigs(loc) {
+    if (!loc) return;
+
+    if (!isAbsolute(loc)) {
+      loc = path.join(process.cwd(), loc);
+    }
+
+    while (loc !== (loc = path.dirname(loc))) {
+      if (this.options.breakConfig) return;
+
+      var configLoc = path.join(loc, CONFIG_FILENAME);
+      if (exists(configLoc)) this.addConfig(configLoc);
+    }
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  normaliseOptions() {
+    var opts = this.options;
+
+    for (let key in config) {
+      var option = config[key];
+      var val    = opts[key];
+
+      // optional
+      if (!val && option.optional) continue;
+
+      // deprecated
+      if (this.log && val && option.deprecated) {
+        this.log.deprecate(`Deprecated option ${key}: ${option.deprecated}`);
+      }
+
+      // validate
+      if (this.pipeline && val) {
+        val = validateOption(key, val, this.pipeline);
+      }
+
+      // aaliases
+      if (option.alias) {
+        opts[option.alias] = opts[option.alias] || val;
+      } else {
+        opts[key] = val;
+      }
+    }
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  init(opts) {
+    this.mergeOptions(opts, "direct");
+
+    // babelrc option
+    if (opts.babelrc) {
+      for (var loc of (opts.babelrc: Array)) this.addConfig(loc);
+    }
+
+    // resolve all .babelrc files
+    this.findConfigs(opts.filename);
+
+    // merge in env
+    var envKey = process.env.BABEL_ENV || process.env.NODE_ENV || "development";
+    if (this.options.env) {
+      this.mergeOptions(this.options.env[envKey], `direct.env.${envKey}`);
+    }
+
+    // normalise
+    this.normaliseOptions(opts);
+
+    return this.options;
+  }
+}

src/babel/transformation/file/options/parsers.js

@@ -1,9 +1,18 @@
+import slash from "slash";
 import * as util from "../../../util";
 
+/**
+ * Get a transformer list from a value.
+ */
+
 export function transformerList(val) {
   return util.arrayify(val);
 }
 
+/**
+ * Validate transformer list. Maps "all" to all transformer names.
+ */
+
 transformerList.validate = function (key, val, pipeline) {
   if (val.indexOf("all") >= 0 || val.indexOf(true) >= 0) {
     val = Object.keys(pipeline.transformers);
@@ -12,18 +21,40 @@ transformerList.validate = function (key, val, pipeline) {
   return pipeline._ensureTransformerNames(key, val);
 };
 
+/**
+ * Cast a value to a number.
+ */
+
 export function number(val) {
   return +val;
 }
 
+/**
+ * Cast a value to a boolean.
+ */
+
+export var filename = slash;
+
+/**
+ * [Please add a description.]
+ */
+
 export function boolean(val) {
   return !!val;
 }
 
+/**
+ * Cast a boolean-like string to a boolean.
+ */
+
 export function booleanString(val) {
   return util.booleanify(val);
 }
 
+/**
+ * Cast a value to an array, splitting strings by ",".
+ */
+
 export function list(val) {
   return util.list(val);
 }

src/babel/transformation/file/options/resolve-rc.js

@@ -1,62 +0,0 @@
-import stripJsonComments from "strip-json-comments";
-import { normaliseOptions } from "./index";
-import merge from "../../../helpers/merge";
-import path from "path";
-import fs from "fs";
-
-var cache = {};
-var jsons = {};
-
-function exists(filename) {
-  if (!fs.existsSync) return false;
-
-  var cached = cache[filename];
-  if (cached != null) return cached;
-  return cache[filename] = fs.existsSync(filename);
-}
-
-export default function (loc, opts = {}) {
-  var rel = ".babelrc";
-
-  if (!opts.babelrc) {
-    opts.babelrc = [];
-  }
-
-  function find(start, rel) {
-    var file = path.join(start, rel);
-
-    if (opts.babelrc.indexOf(file) >= 0) {
-      return;
-    }
-
-    if (exists(file)) {
-      var content = fs.readFileSync(file, "utf8");
-      var json;
-
-      try {
-        json = jsons[content] = jsons[content] || JSON.parse(stripJsonComments(content));
-        normaliseOptions(json);
-      } catch (err) {
-        err.message = `${file}: ${err.message}`;
-        throw err;
-      }
-
-      opts.babelrc.push(file);
-
-      if (json.breakConfig) return;
-
-      merge(opts, json);
-    }
-
-    var up = path.dirname(start);
-    if (up !== start) { // root
-      find(up, rel);
-    }
-  }
-
-  if (opts.babelrc.indexOf(loc) < 0 && opts.breakConfig !== true) {
-    find(loc, rel);
-  }
-
-  return opts;
-}

src/babel/transformation/file/plugin-manager.js

@@ -2,9 +2,13 @@ import Transformer from "../transformer";
 import Plugin from "../plugin";
 import * as types from "../../types";
 import * as messages from "../../messages";
-import traverse from "../../types";
+import traverse from "../../traversal";
 import parse from "../../helpers/parse";
 
+/**
+ * [Please add a description.]
+ */
+
 var context = {
   messages,
   Transformer,
@@ -16,9 +20,22 @@ var context = {
 
 import * as util from  "../../util";
 
+/**
+ * [Please add a description.]
+ */
+
 export default class PluginManager {
+
+  /**
+   * [Please add a description.]
+   */
+
   static memoisedPlugins = [];
 
+  /**
+   * [Please add a description.]
+   */
+
   static memoisePluginContainer(fn) {
     for (var i = 0; i < PluginManager.memoisedPlugins.length; i++) {
       var plugin = PluginManager.memoisedPlugins[i];
@@ -33,8 +50,16 @@ export default class PluginManager {
     return transformer;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   static positions = ["before", "after"];
 
+  /**
+   * [Please add a description.]
+   */
+
   constructor({ file, transformers, before, after } = { transformers: {}, before: [], after: [] }) {
     this.transformers = transformers;
     this.file         = file;
@@ -42,6 +67,10 @@ export default class PluginManager {
     this.after        = after;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   subnormaliseString(name, position) {
     // this is a plugin in the form of "foobar" or "foobar:after"
     // where the optional colon is the delimiter for plugin position in the transformer stack
@@ -61,6 +90,10 @@ export default class PluginManager {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   validate(name, plugin) {
     // validate transformer key
     var key = plugin.key;
@@ -77,6 +110,10 @@ export default class PluginManager {
     plugin.metadata.plugin = true;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   add(name) {
     var position;
     var plugin;

src/babel/transformation/helpers/README.md

@@ -0,0 +1,3 @@
+## Transformation Helpers
+
+This is the Transformation Helpers directory.

src/babel/transformation/helpers/build-binary-assignment-operator-transformer.js

@@ -1,17 +1,33 @@
 import explode from "./explode-assignable-expression";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (opts) {
   var exports = {};
 
+  /**
+   * [Please add a description.]
+   */
+
   var isAssignment = function (node) {
     return node.operator === opts.operator + "=";
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   var buildAssignment = function (left, right) {
     return t.assignmentExpression("=", left, right);
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   exports.ExpressionStatement = function (node, parent, scope, file) {
     // hit the `AssignmentExpression` one below
     if (this.isCompletionRecord()) return;
@@ -29,6 +45,10 @@ export default function (opts) {
     return nodes;
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   exports.AssignmentExpression = function (node, parent, scope, file) {
     if (!isAssignment(node)) return;
 
@@ -38,6 +58,10 @@ export default function (opts) {
     return nodes;
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   exports.BinaryExpression = function (node) {
     if (node.operator !== opts.operator) return;
     return opts.build(node.left, node.right);

src/babel/transformation/helpers/build-comprehension.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function build(node, buildBody) {
   var self = node.blocks.shift();
   if (!self) return;

src/babel/transformation/helpers/build-conditional-assignment-operator-transformer.js

@@ -1,11 +1,24 @@
 import explode from "./explode-assignable-expression";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (exports, opts) {
+
+  /**
+   * [Please add a description.]
+   */
+
   var buildAssignment = function (left, right) {
     return t.assignmentExpression("=", left, right);
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   exports.ExpressionStatement = function (node, parent, scope, file) {
     // hit the `AssignmentExpression` one below
     if (this.isCompletionRecord()) return;
@@ -25,6 +38,10 @@ export default function (exports, opts) {
     return nodes;
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   exports.AssignmentExpression = function (node, parent, scope, file) {
     if (!opts.is(node, file)) return;
 

src/babel/transformation/helpers/build-react-transformer.js

@@ -9,9 +9,17 @@ import esutils from "esutils";
 import * as react from "./react";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (opts) {
   var visitor = {};
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXIdentifier = function (node) {
     if (node.name === "this" && this.isReferenced()) {
       return t.thisExpression();
@@ -22,10 +30,18 @@ export default function (opts) {
     }
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXNamespacedName = function () {
     throw this.errorWithNode(messages.get("JSXNamespacedTags"));
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXMemberExpression = {
     exit(node) {
       node.computed = t.isLiteral(node.property);
@@ -33,10 +49,18 @@ export default function (opts) {
     }
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXExpressionContainer = function (node) {
     return node.expression;
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXAttribute = {
     enter(node) {
       var value = node.value;
@@ -51,6 +75,10 @@ export default function (opts) {
     }
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXOpeningElement = {
     exit(node, parent, scope, file) {
       parent.children = react.buildChildren(parent);
@@ -141,6 +169,10 @@ export default function (opts) {
     return attribs;
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXElement = {
     exit(node) {
       var callExpr = node.openingElement;

src/babel/transformation/helpers/call-delegate.js

@@ -1,6 +1,15 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 var visitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   enter(node, parent, scope, state) {
     if (this.isThisExpression() || this.isReferencedIdentifier({ name: "arguments" })) {
       state.found = true;
@@ -8,11 +17,19 @@ var visitor = {
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   Function() {
     this.skip();
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (node, scope) {
   var container = t.functionExpression(null, [], node.body, node.generator, node.async);
 

src/babel/transformation/helpers/define-map.js

@@ -2,6 +2,10 @@ import each from "lodash/collection/each";
 import has from "lodash/object/has";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export function push(mutatorMap, node, kind, file) {
   var alias = t.toKeyAlias(node);
 
@@ -43,6 +47,10 @@ export function push(mutatorMap, node, kind, file) {
   return map;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function hasComputed(mutatorMap) {
   for (var key in mutatorMap) {
     if (mutatorMap[key]._computed) {
@@ -52,6 +60,10 @@ export function hasComputed(mutatorMap) {
   return false;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function toComputedObjectFromClass(obj) {
   var objExpr = t.arrayExpression([]);
 
@@ -65,6 +77,10 @@ export function toComputedObjectFromClass(obj) {
   return objExpr;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function toClassObject(mutatorMap) {
   var objExpr = t.objectExpression([]);
 
@@ -92,6 +108,10 @@ export function toClassObject(mutatorMap) {
   return objExpr;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function toDefineObject(mutatorMap) {
   each(mutatorMap, function (map) {
     if (map.value) map.writable = t.literal(true);

src/babel/transformation/helpers/explode-assignable-expression.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 var getObjRef = function (node, nodes, file, scope) {
   var ref;
   if (t.isIdentifier(node)) {
@@ -33,6 +37,10 @@ var getObjRef = function (node, nodes, file, scope) {
   return temp;
 };
 
+/**
+ * [Please add a description.]
+ */
+
 var getPropRef = function (node, nodes, file, scope) {
   var prop = node.property;
   var key = t.toComputedKey(node, prop);
@@ -45,6 +53,10 @@ var getPropRef = function (node, nodes, file, scope) {
   return temp;
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (node, nodes, file, scope, allowedSingleIdent) {
   var obj;
   if (t.isIdentifier(node) && allowedSingleIdent) {

src/babel/transformation/helpers/get-function-arity.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (node) {
   var lastNonDefault = 0;
   for (var i = 0; i < node.params.length; i++) {

src/babel/transformation/helpers/memoise-decorators.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (decorators, scope) {
   for (var i = 0; i < decorators.length; i++) {
     var decorator = decorators[i];

src/babel/transformation/helpers/name-method.js

@@ -2,6 +2,10 @@ import getFunctionArity from "./get-function-arity";
 import * as util from  "../../util";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 function visitIdentifier(context, node, scope, state) {
   // check if this node matches our function id
   if (node.name !== state.name) return;
@@ -15,16 +19,33 @@ function visitIdentifier(context, node, scope, state) {
   context.stop();
 }
 
+/**
+ * [Please add a description.]
+ */
+
 var visitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   ReferencedIdentifier(node, parent, scope, state) {
     visitIdentifier(this, node, scope, state);
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   BindingIdentifier(node, parent, scope, state) {
     visitIdentifier(this, node, scope, state);
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 var wrap = function (state, method, id, scope) {
   if (state.selfReference) {
     if (scope.hasBinding(id.name) && !scope.hasGlobal(id.name)) {
@@ -56,6 +77,10 @@ var wrap = function (state, method, id, scope) {
   scope.getProgramParent().references[id.name] = true;
 };
 
+/**
+ * [Please add a description.]
+ */
+
 var visit = function (node, name, scope) {
   var state = {
     selfAssignment: false,
@@ -102,11 +127,19 @@ var visit = function (node, name, scope) {
   return state;
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export function custom(node, id, scope) {
   var state = visit(node, id.name, scope);
   return wrap(state, node, id, scope);
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function property(node, file, scope) {
   var key = t.toComputedKey(node, node.key);
   if (!t.isLiteral(key)) return; // we can't set a function id with this
@@ -119,6 +152,10 @@ export function property(node, file, scope) {
   node.value = wrap(state, method, id, scope) || method;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function bare(node, parent, scope) {
   // has an `id` so we don't need to infer one
   if (node.id) return;

src/babel/transformation/helpers/react.js

@@ -2,10 +2,18 @@ import * as t from "../../types";
 
 export var isReactComponent = t.buildMatchMemberExpression("React.Component");
 
+/**
+ * [Please add a description.]
+ */
+
 export function isCompatTag(tagName) {
   return tagName && /^[a-z]|\-/.test(tagName);
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function cleanJSXElementLiteralChild(child, args) {
   var lines = child.value.split(/\r\n|\n|\r/);
 
@@ -51,6 +59,10 @@ function cleanJSXElementLiteralChild(child, args) {
   if (str) args.push(t.literal(str));
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function buildChildren(node) {
   var elems = [];
 

src/babel/transformation/helpers/regex.js

@@ -1,10 +1,18 @@
 import pull from "lodash/array/pull";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export function is(node, flag) {
   return t.isLiteral(node) && node.regex && node.regex.flags.indexOf(flag) >= 0;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function pullFlag(node, flag) {
   var flags = node.regex.flags.split("");
   if (node.regex.flags.indexOf(flag) < 0) return;

src/babel/transformation/helpers/remap-async-to-generator.js

@@ -1,10 +1,23 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 var awaitVisitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   Function() {
     this.skip();
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   AwaitExpression(node) {
     node.type = "YieldExpression";
 
@@ -16,7 +29,16 @@ var awaitVisitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 var referenceVisitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   ReferencedIdentifier(node, parent, scope, state) {
     var name = state.id.name;
     if (node.name === name && scope.bindingIdentifierEquals(name, state.id)) {
@@ -25,6 +47,10 @@ var referenceVisitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (path, callId) {
   var node = path.node;
 

src/babel/transformation/helpers/replace-supers.js

@@ -2,6 +2,10 @@ import type NodePath from "../../traversal/path";
 import * as messages from "../../messages";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 function isIllegalBareSuper(node, parent) {
   if (!t.isSuper(node)) return false;
   if (t.isMemberExpression(parent, { computed: false })) return false;
@@ -9,11 +13,24 @@ function isIllegalBareSuper(node, parent) {
   return true;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function isMemberExpressionSuper(node) {
   return t.isMemberExpression(node) && t.isSuper(node.object);
 }
 
+/**
+ * [Please add a description.]
+ */
+
 var visitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   enter(node, parent, scope, state) {
     var topLevel = state.topLevel;
     var self = state.self;
@@ -44,12 +61,11 @@ var visitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default class ReplaceSupers {
-
-  /**
-   * Description
-   */
-
   constructor(opts: Object, inClass?: boolean = false) {
     this.topLevelThisReference = opts.topLevelThisReference;
     this.methodPath            = opts.methodPath;
@@ -64,6 +80,10 @@ export default class ReplaceSupers {
     this.opts                  = opts;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getObjectRef() {
     return this.opts.objectRef || this.opts.getObjectRef();
   }
@@ -120,7 +140,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   replace() {
@@ -128,7 +148,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   traverseLevel(path: NodePath, topLevel: boolean) {
@@ -137,7 +157,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   getThisReference() {
@@ -153,7 +173,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   getLooseSuperProperty(id: Object, parent: Object) {
@@ -196,7 +216,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   looseHandle(path: NodePath, getThisReference: Function) {
@@ -216,7 +236,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   specHandleAssignmentExpression(ref, path, node, getThisReference) {
@@ -238,7 +258,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   specHandle(path: NodePath, getThisReference: Function) {

src/babel/transformation/index.js

@@ -1,8 +1,14 @@
 import Pipeline from "./pipeline";
 
+/**
+ * [Please add a description.]
+ */
+
 var pipeline = new Pipeline;
 
-//
+/**
+ * [Please add a description.]
+ */
 
 import transformers from "./transformers";
 
@@ -17,17 +23,23 @@ for (var key in transformers) {
 
 pipeline.addTransformers(transformers);
 
-//
+/**
+ * [Please add a description.]
+ */
 
 import deprecated from "./transformers/deprecated";
 pipeline.addDeprecated(deprecated);
 
-//
+/**
+ * [Please add a description.]
+ */
 
 import aliases from "./transformers/aliases";
 pipeline.addAliases(aliases);
 
-//
+/**
+ * [Please add a description.]
+ */
 
 import * as filters from "./transformers/filters";
 pipeline.addFilter(filters.internal);
@@ -36,7 +48,9 @@ pipeline.addFilter(filters.whitelist);
 pipeline.addFilter(filters.stage);
 pipeline.addFilter(filters.optional);
 
-//
+/**
+ * [Please add a description.]
+ */
 
 var transform = pipeline.transform.bind(pipeline);
 transform.fromAst = pipeline.transformFromAst.bind(pipeline);

src/babel/transformation/modules/README.md

@@ -0,0 +1,3 @@
+## Module Transformation
+
+This is the Module Transformation directory.

src/babel/transformation/modules/_default.js

@@ -5,7 +5,16 @@ import object from "../../helpers/object";
 import * as util from  "../../util";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 var metadataVisitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   ModuleDeclaration: {
     enter(node, parent, scope, formatter) {
       if (node.source) {
@@ -15,6 +24,10 @@ var metadataVisitor = {
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   ImportDeclaration: {
     exit(node, parent, scope, formatter) {
       formatter.hasLocalImports = true;
@@ -63,6 +76,10 @@ var metadataVisitor = {
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   ExportDeclaration(node, parent, scope, formatter) {
     formatter.hasLocalExports = true;
 
@@ -156,6 +173,10 @@ var metadataVisitor = {
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   Scope(node, parent, scope, formatter) {
     if (!formatter.isLoose()) {
       this.skip();
@@ -163,6 +184,10 @@ var metadataVisitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default class DefaultFormatter {
   constructor(file) {
     // object containg all module sources with the scope that they're contained in
@@ -190,6 +215,10 @@ export default class DefaultFormatter {
     this.getMetadata();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addScope(path) {
     var source = path.node.source && path.node.source.value;
     if (!source) return;
@@ -202,19 +231,35 @@ export default class DefaultFormatter {
     this.sourceScopes[source] = path.scope;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   isModuleType(node, type) {
     var modules = this.file.dynamicImportTypes[type];
     return modules && modules.indexOf(node) >= 0;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   transform() {
     this.remapAssignments();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   doDefaultExportInterop(node) {
     return (t.isExportDefaultDeclaration(node) || t.isSpecifierDefault(node)) && !this.noInteropRequireExport && !this.hasNonDefaultExports;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getMetadata() {
     var has = false;
     for (var node of (this.file.ast.program.body: Array)) {
@@ -228,12 +273,20 @@ export default class DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   remapAssignments() {
     if (this.hasLocalExports || this.hasLocalImports) {
       this.remaps.run();
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   remapExportAssignment(node, exported) {
     var assign = node;
 
@@ -248,6 +301,10 @@ export default class DefaultFormatter {
     return assign;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _addExport(name, exported) {
     var info = this.localExports[name] = this.localExports[name] || {
       binding: this.scope.getBindingIdentifier(name),
@@ -256,6 +313,10 @@ export default class DefaultFormatter {
     info.exported.push(exported);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getExport(node, scope) {
     if (!t.isIdentifier(node)) return;
 
@@ -265,6 +326,10 @@ export default class DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getModuleName() {
     var opts = this.file.opts;
     // moduleId is n/a if a `getModuleId()` is provided
@@ -307,6 +372,10 @@ export default class DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _pushStatement(ref, nodes) {
     if (t.isClass(ref) || t.isFunction(ref)) {
       if (ref.id) {
@@ -318,6 +387,10 @@ export default class DefaultFormatter {
     return ref;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _hoistExport(declar, assign, priority) {
     if (t.isFunctionDeclaration(declar)) {
       assign._blockHoist = priority || 2;
@@ -326,6 +399,10 @@ export default class DefaultFormatter {
     return assign;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getExternalReference(node, nodes) {
     var ids = this.ids;
     var id = node.source.value;
@@ -337,21 +414,37 @@ export default class DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   checkExportIdentifier(node) {
     if (t.isIdentifier(node, { name: "__esModule" })) {
       throw this.file.errorWithNode(node, messages.get("modulesIllegalExportName", node.name));
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportAllDeclaration(node, nodes) {
     var ref = this.getExternalReference(node, nodes);
     nodes.push(this.buildExportsWildcard(ref, node));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   isLoose() {
     return this.file.isLoose("es6.modules");
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportSpecifier(specifier, node, nodes) {
     if (node.source) {
       var ref = this.getExternalReference(node, nodes);
@@ -376,6 +469,10 @@ export default class DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildExportsWildcard(objectIdentifier) {
     return t.expressionStatement(t.callExpression(this.file.addHelper("defaults"), [
       t.identifier("exports"),
@@ -383,6 +480,10 @@ export default class DefaultFormatter {
     ]));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildExportsFromAssignment(id, init) {
     this.checkExportIdentifier(id);
     return util.template("exports-from-assign", {
@@ -391,6 +492,10 @@ export default class DefaultFormatter {
     }, true);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildExportsAssignment(id, init) {
     this.checkExportIdentifier(id);
     return util.template("exports-assign", {
@@ -399,6 +504,10 @@ export default class DefaultFormatter {
     }, true);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportDeclaration(node, nodes) {
     var declar = node.declaration;
 

src/babel/transformation/modules/_strict.js

@@ -1,5 +1,9 @@
 import * as util from "../../util";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (Parent) {
   var Constructor = function () {
     this.noInteropRequireImport = true;

src/babel/transformation/modules/amd-strict.js

@@ -1,3 +1,8 @@
 import AMDFormatter from "./amd";
 import buildStrict from "./_strict";
+
+/**
+ * [Please add a description.]
+ */
+
 export default buildStrict(AMDFormatter);

src/babel/transformation/modules/amd.js

@@ -5,11 +5,24 @@ import values from "lodash/object/values";
 import * as util from  "../../util";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default class AMDFormatter extends DefaultFormatter {
+
+  /**
+   * [Please add a description.]
+   */
+
   setup() {
     CommonFormatter.prototype._setup.call(this, this.hasNonDefaultExports);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildDependencyLiterals() {
     var names = [];
     for (var name in this.ids) {
@@ -64,14 +77,26 @@ export default class AMDFormatter extends DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _getExternalReference(node) {
     return this.scope.generateUidIdentifier(node.source.value);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   importDeclaration(node) {
     this.getExternalReference(node);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   importSpecifier(specifier, node, nodes, scope) {
     var key = node.source.value;
     var ref = this.getExternalReference(node);
@@ -105,6 +130,10 @@ export default class AMDFormatter extends DefaultFormatter {
     this.remaps.add(scope, specifier.local.name, ref);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportSpecifier(specifier, node, nodes) {
     if (this.doDefaultExportInterop(specifier)) {
       this.passModuleArg = true;
@@ -120,6 +149,10 @@ export default class AMDFormatter extends DefaultFormatter {
     CommonFormatter.prototype.exportSpecifier.apply(this, arguments);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportDeclaration(node, nodes) {
     if (this.doDefaultExportInterop(node)) {
       this.passModuleArg = true;