Merge pull request #5613 from babel/backport-doc-changes

Backport doc changes

packages/babel-generator/README.md

@@ -54,12 +54,7 @@ sourceFileName         | string   |                 | The filename for the sourc
 In most cases, Babel does a 1:1 transformation of input-file to output-file.  However,
 you may be dealing with AST constructed from multiple sources - JS files, templates, etc.
 If this is the case, and you want the sourcemaps to reflect the correct sources, you'll need
-to make some changes to your code.
+to pass an object to `generate` as the `code` parameter.  Keys
-
-First, each node with a `loc` property (which indicates that node's original placement in the
-source document) must also include a `loc.filename` property, set to the source filename.
-
-Second, you should pass an object to `generate` as the `code` parameter.  Keys
 should be the source filenames, and values should be the source content.
 
 Here's an example of what that might look like:
@@ -70,14 +65,14 @@ import generate from 'babel-generator';
 
 const a = 'var a = 1;';
 const b = 'var b = 2;';
-const astA = parse(a, { filename: 'a.js' });
+const astA = parse(a, { sourceFilename: 'a.js' });
-const astB = parse(b, { filename: 'b.js' });
+const astB = parse(b, { sourceFilename: 'b.js' });
 const ast = {
   type: 'Program',
-  body: [].concat(astA.body, ast2.body)
+  body: [].concat(astA.program.body, astB.program.body)
 };
 
-const { code, map } = generate(ast, { /* options */ }, {
+const { code, map } = generate(ast, { sourceMaps: true }, {
   'a.js': a,
   'b.js': b
 });

packages/babel-plugin-transform-es2015-arrow-functions/README.md

@@ -27,12 +27,12 @@ console.log(bob.printFriends());
 **Out**
 
 ```javascript
-var a = function a() {};
+var a = function () {};
-var a = function a(b) {
+var a = function (b) {
   return b;
 };
 
-var double = [1, 2, 3].map(function (num) {
+const double = [1, 2, 3].map(function (num) {
   return num * 2;
 });
 console.log(double); // [2,4,6]
@@ -40,7 +40,7 @@ console.log(double); // [2,4,6]
 var bob = {
   _name: "Bob",
   _friends: ["Sally", "Tom"],
-  printFriends: function printFriends() {
+  printFriends() {
     var _this = this;
 
     this._friends.forEach(function (f) {

packages/babel-plugin-transform-es2015-modules-commonjs/README.md

@@ -82,7 +82,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 ```
 
-In environments that don't support this you can enable loose mode on `babel-plugin-transform-es20150-modules-commonjs`
+In environments that don't support this you can enable loose mode on `babel-plugin-transform-es2015-modules-commonjs`
 and instead of using `Object.defineProperty` an assignment will be used instead.
 
 ```javascript

packages/babel-plugin-transform-es2015-spread/README.md

@@ -9,31 +9,13 @@
 ```js
 var a = ['a', 'b', 'c'];
 var b = [...a, 'foo'];
-
-var c = { foo: 'bar', baz: 42 };
-var d = {...c, a: 2};
 ```
 
 **Out**
 
 ```js
-var _extends = Object.assign || function (target) {
-  for (var i = 1; i < arguments.length; i++) {
-    var source = arguments[i];
-    for (var key in source) {
-      if (Object.prototype.hasOwnProperty.call(source, key)) {
-        target[key] = source[key];
-      }
-    }
-  }
-  return target;
-}
-
 var a = [ 'a', 'b', 'c' ];
 var b = [].concat(a, [ 'foo' ]);
-
-var c = { foo: 'bar', baz: 42 };
-var d = _extends({}, c, { a: 2 });
 ```
 
 ## Installation

packages/babel-plugin-transform-runtime/README.md

@@ -1,8 +1,8 @@
 # babel-plugin-transform-runtime
 
-> Externalise references to helpers and builtins, automatically polyfilling your code without polluting globals. (This plugin is recommended in a library/tool)
+> Externalise references to helpers and built-ins, automatically polyfilling your code without polluting globals. (This plugin is recommended in a library/tool)
 
-NOTE: Instance methods such as `"foobar".includes("foo")` will not work since that would require modification of existing builtins (Use [`babel-polyfill`](http://babeljs.io/docs/usage/polyfill) for that).
+NOTE: Instance methods such as `"foobar".includes("foo")` will not work since that would require modification of existing built-ins (Use [`babel-polyfill`](http://babeljs.io/docs/usage/polyfill) for that).
 
 ## Why?
 
@@ -54,10 +54,10 @@ With options:
 {
   "plugins": [
     ["transform-runtime", {
-      "helpers": false, // defaults to true
+      "helpers": false,
-      "polyfill": false, // defaults to true
+      "polyfill": false,
-      "regenerator": true, // defaults to true
+      "regenerator": true,
-      "moduleName": "babel-runtime" // defaults to "babel-runtime"
+      "moduleName": "babel-runtime"
     }]
   ]
 }
@@ -77,15 +77,59 @@ require("babel-core").transform("code", {
 });
 ```
 
+## Options
+
+### `helpers`
+
+`boolean`, defaults to `true`.
+
+Toggles whether or not inlined Babel helpers (`classCallCheck`, `extends`, etc.) are replaced with calls to `moduleName`.
+
+For more information, see [Helper aliasing](#helper-aliasing).
+
+### `polyfill`
+
+`boolean`, defaults to `true`.
+
+Toggles whether or not new built-ins (`Promise`, `Set`, `Map`, etc.) are transformed to use a non-global polluting polyfill.
+
+For more information, see [`core-js` aliasing](#core-js-aliasing).
+
+### `regenerator`
+
+`boolean`, defaults to `true`.
+
+Toggles whether or not generator functions are transformed to use a regenerator runtime that does not pollute the global scope.
+
+For more information, see [Regenerator aliasing](#regenerator-aliasing).
+
+### `moduleName`
+
+`string`, defaults to `"babel-runtime"`.
+
+Sets the name/path of the module used when importing helpers.
+
+Example:
+
+```json
+{
+  "moduleName": "flavortown/runtime"
+}
+```
+
+```js
+import extends from 'flavortown/runtime/helpers/extends';
+```
+
 ## Technical details
 
 The `runtime` transformer plugin does three things:
 
 * Automatically requires `babel-runtime/regenerator` when you use generators/async functions.
 * Automatically requires `babel-runtime/core-js` and maps ES6 static methods and built-ins.
-* Removes the inline babel helpers and uses the module `babel-runtime/helpers` instead.
+* Removes the inline Babel helpers and uses the module `babel-runtime/helpers` instead.
 
-What does this actually mean though? Basically, you can use built-ins such as `Promise`, `Set`, `Symbol` etc as well use all the Babel features that require a polyfill seamlessly, without global pollution, making it extremely suitable for libraries.
+What does this actually mean though? Basically, you can use built-ins such as `Promise`, `Set`, `Symbol`, etc., as well use all the Babel features that require a polyfill seamlessly, without global pollution, making it extremely suitable for libraries.
 
 Make sure you include `babel-runtime` as a dependency.
 
@@ -194,7 +238,7 @@ without worrying about where they come from.
 
 ### Helper aliasing
 
-Usually babel will place helpers at the top of your file to do common tasks to avoid
+Usually Babel will place helpers at the top of your file to do common tasks to avoid
 duplicating the code around in the current file. Sometimes these helpers can get a
 little bulky and add unnecessary duplication across files. The `runtime`
 transformer replaces all the helper calls to a module.

packages/babel-register/README.md

@@ -5,7 +5,7 @@
 One of the ways you can use Babel is through the require hook. The require hook
 will bind itself to node's `require` and automatically compile files on the
 fly. This is equivalent to CoffeeScript's
-[coffee-script/register](http://coffeescript.org/documentation/docs/register.html).
+[coffee-script/register](http://coffeescript.org/v2/annotated-source/register.html).
 
 ## Install
 
@@ -66,7 +66,10 @@ require("babel-register")({
 
   // Setting this will remove the currently hooked extensions of .es6, `.es`, `.jsx`
   // and .js so you'll have to add them back if you want them to be used again.
-  extensions: [".es6", ".es", ".jsx", ".js"]
+  extensions: [".es6", ".es", ".jsx", ".js"],
+
+  // Setting this to false will disable the cache.
+  cache: true
 });
 ```