Update transform-es2015 READMEs from babel.github.io [skip ci] (#4926)

Signed-off-by: Brian Ng <bng412@gmail.com>

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

@@ -1,6 +1,57 @@
 # babel-plugin-transform-es2015-arrow-functions
 
-Compile ES2015 arrow functions to ES5
+> Compile ES2015 arrow functions to ES5
+
+## Example
+
+**In**
+
+```javascript
+var a = () => {};
+var a = (b) => b;
+
+const double = [1,2,3].map((num) => num * 2);
+console.log(double); // [2,4,6]
+
+var bob = {
+  _name: "Bob",
+  _friends: ["Sally", "Tom"],
+  printFriends() {
+    this._friends.forEach(f =>
+      console.log(this._name + " knows " + f));
+  }
+};
+console.log(bob.printFriends());
+```
+
+**Out**
+
+```javascript
+var a = function a() {};
+var a = function a(b) {
+  return b;
+};
+
+var double = [1, 2, 3].map(function (num) {
+  return num * 2;
+});
+console.log(double); // [2,4,6]
+
+var bob = {
+  _name: "Bob",
+  _friends: ["Sally", "Tom"],
+  printFriends: function printFriends() {
+    var _this = this;
+
+    this._friends.forEach(function (f) {
+      return console.log(_this._name + " knows " + f);
+    });
+  }
+};
+console.log(bob.printFriends());
+```
+
+[Try in REPL](http://babeljs.io/repl/#?evaluate=true&lineWrap=true&presets=es2015%2Ces2015-loose&experimental=false&loose=false&spec=false&code=var%20a%20%3D%20()%20%3D%3E%20%7B%7D%3B%0Avar%20a%20%3D%20(b)%20%3D%3E%20b%3B%0A%0Aconst%20double%20%3D%20%5B1%2C2%2C3%5D.map((num)%20%3D%3E%20num%20*%202)%3B%0Aconsole.log(double)%3B%20%2F%2F%20%5B2%2C4%2C6%5D%0A%0Avar%20bob%20%3D%20%7B%0A%20%20_name%3A%20%22Bob%22%2C%0A%20%20_friends%3A%20%5B%22Sally%22%2C%20%22Tom%22%5D%2C%0A%20%20printFriends()%20%7B%0A%20%20%20%20this._friends.forEach(f%20%3D%3E%0A%20%20%20%20%20%20console.log(this._name%20%2B%20%22%20knows%20%22%20%2B%20f))%3B%0A%20%20%7D%0A%7D%3B%0Aconsole.log(bob.printFriends())%3B&playground=true)
 
 ## Installation
 
@@ -41,3 +92,7 @@ require("babel-core").transform("code", {
   plugins: ["transform-es2015-arrow-functions"]
 });
 ```
+
+## Options
+
+* `spec` - This option wraps the generated function in `.bind(this)` and keeps uses of `this` inside the function as-is, instead of using a renamed `this`. It also adds a runtime check to ensure the functions are not instantiated.

packages/babel-plugin-transform-es2015-block-scoped-functions/README.md

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-block-scoped-functions
 
-Babel plugin to ensure function declarations at the block level are block scoped.
+> Babel plugin to ensure function declarations at the block level are block scoped.
 
 ## Installation
 

packages/babel-plugin-transform-es2015-block-scoping/README.md

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-block-scoping
 
-Compile ES2015 block scoping (const and let) to ES5
+> Compile ES2015 block scoping (const and let) to ES5
 
 ## Installation
 

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

@@ -1,6 +1,12 @@
 # babel-plugin-transform-es2015-classes
 
-Compile ES2015 classes to ES5
+> Compile ES2015 classes to ES5
+
+## Caveats
+
+Built-in classes such as `Date`, `Array`, `DOM` etc cannot be properly subclassed
+due to limitations in ES5 (for the [es2015-classes](/docs/plugins/transform-es2015-classes) plugin).
+You can try to use [babel-plugin-transform-builtin-extend](https://github.com/loganfsmyth/babel-plugin-transform-builtin-extend) based on `Object.setPrototypeOf` and `Reflect.construct`, but it also has some limitations.
 
 ## Installation
 
@@ -43,3 +49,55 @@ require("babel-core").transform("code", {
   plugins: ["transform-es2015-classes"]
 });
 ```
+
+## Options `loose`
+
+#### Method enumerability
+
+Please note that in loose mode class methods **are** enumerable. This is not in line
+with the spec and you may run into issues.
+
+#### Method assignment
+
+Under loose mode, methods are defined on the class prototype with simple assignments
+instead of being defined. This can result in the following not working:
+
+```javascript
+class Foo {
+  set bar() {
+    throw new Error("foo!");
+  }
+}
+
+class Bar extends Foo {
+  bar() {
+    // will throw an error when this method is defined
+  }
+}
+```
+
+When `Bar.prototype.foo` is defined it triggers the setter on `Foo`. This is a
+case that is very unlikely to appear in production code however it's something
+to keep in mind.
+
+## Usage
+
+### Via `.babelrc` (Recommended)
+
+**.babelrc**
+
+```js
+// without options
+{
+  "plugins": ["transform-es2015-classes"]
+}
+
+// with options
+{
+  "plugins": [
+    ["transform-es2015-classes", {
+      "loose": true
+    }]
+  ]
+}
+```

packages/babel-plugin-transform-es2015-computed-properties/README.md

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-computed-properties
 
-Compile ES2015 computed properties to ES5
+> Compile ES2015 computed properties to ES5
 
 ## Installation
 
@@ -43,3 +43,9 @@ require("babel-core").transform("code", {
   plugins: ["transform-es2015-computed-properties"]
 });
 ```
+
+## Options
+
+* `loose` - Just like method assignment in classes, in loose mode, computed property names
+use simple assignments instead of being defined. This is unlikely to be an issue
+in production code.

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

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-destructuring
 
-Compile ES2015 destructuring to ES5
+> Compile ES2015 destructuring to ES5
 
 ## Installation
 

packages/babel-plugin-transform-es2015-duplicate-keys/README.md

@@ -1,11 +1,30 @@
 # babel-plugin-transform-es2015-duplicate-keys
 
-Compile objects with duplicate keys to valid strict ES5.
+> Compile objects with duplicate keys to valid strict ES5. This plugin actually converts duplicate keys in objects to be computed properties, which then must be handled by the [transform-es2015-computed-properties](/docs/plugins/transform-es2015-computed-properties) plugin. The final result won't contain any object literals with duplicate keys.
 
-This plugin actually converts duplicate keys in objects to be computed
-properties, which then must be handled by the
-transform-es2015-computed-properties plugin. The final result won't contain any
-object literals with duplicate keys.
+## Example
+
+**In**
+
+```javascript
+var x = { a: 5, a: 6 };
+var y = {
+  get a() {},
+  set a(x) {},
+  a: 3
+};
+```
+
+**Out**
+
+```javascript
+var x = { a: 5, ["a"]: 6 };
+var y = {
+  get a() {},
+  set a(x) {},
+  ["a"]: 3
+};
+```
 
 ## Installation
 

packages/babel-plugin-transform-es2015-for-of/README.md

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-for-of
 
-Compile ES2015 for...of to ES5
+> Compile ES2015 for...of to ES5
 
 ## Installation
 
@@ -43,3 +43,69 @@ require("babel-core").transform("code", {
   plugins: ["transform-es2015-for-of"]
 });
 ```
+
+## Options `loose`
+
+#### Abrupt completions
+
+In loose mode an iterators `return` method will not be called on abrupt completions caused by thrown errors.
+
+Please see [google/traceur-compiler#1773](https://github.com/google/traceur-compiler/issues/1773) and
+[babel/babel#838](https://github.com/babel/babel/issues/838) for more information.
+
+#### Arrays
+
+Under loose mode the `forOf` transformer will output more verbose iteration code.
+
+For example the following:
+
+```javascript
+for (var i of foo) {}
+```
+
+is normally output as:
+
+```javascript
+for (var _iterator = foo[Symbol.iterator](), _step; !(_step = _iterator.next()).done;) {
+  var i = _step.value;
+}
+```
+
+Under loose mode however it's output as:
+
+```javascript
+for (var _iterator = foo, _isArray = Array.isArray(_iterator), _i = 0, _iterator = _isArray ? _iterator : _iterator[Symbol.iterator]();;) {
+  var i;
+  if (_isArray) {
+    if (_i >= _iterator.length) break;
+    i = _iterator[_i++];
+  } else {
+    _i = _iterator.next();
+    if (_i.done) break;
+    i = _i.value;
+  }
+}
+```
+
+The result is that arrays are put in a fast path, heavily increasing performance.
+All other iterables will continue to work fine but array iteration will be
+significantly faster.
+
+### Optimization
+
+If a basic array is used, Babel will compile the for-of loop down to a regular for loop.
+
+**In**
+
+```js
+for (let a of [1,2,3]) {}
+```
+
+**Out**
+
+```js
+var _arr = [1, 2, 3];
+for (var _i = 0; _i < _arr.length; _i++) {
+  var a = _arr[_i];
+}
+```

packages/babel-plugin-transform-es2015-function-name/README.md

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-function-name
 
-Apply ES2015 function.name semantics to all functions
+> Apply ES2015 function.name semantics to all functions
 
 ## Installation
 

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

@@ -1,6 +1,24 @@
 # babel-plugin-transform-es2015-literals
 
-Compile ES2015 unicode string and number literals to ES5
+> Compile ES2015 unicode string and number literals to ES5
+
+## Example
+
+**In**
+
+```js
+var b = 0b11; // binary integer literal
+var o = 0o7; // octal integer literal
+const u = 'Hello\u{000A}\u{0009}!'; // unicode string literals, newline and tab
+```
+
+**Out**
+
+```js
+var b = 3; // binary integer literal
+var o = 7; // octal integer literal
+const u = 'Hello\n\t!'; // unicode string literals, newline and tab
+```
 
 ## Installation
 

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

@@ -1,5 +1,29 @@
 # babel-plugin-transform-es2015-modules-amd
 
+> This plugin transforms ES2015 modules to [Asynchronous Module Definition (AMD)](https://github.com/amdjs/amdjs-api).
+
+## Example
+
+**In**
+
+```javascript
+export default 42;
+```
+
+**Out**
+
+```javascript
+define(["exports"], function (exports) {
+  "use strict";
+
+  Object.defineProperty(exports, "__esModule", {
+    value: true
+  });
+
+  exports.default = 42;
+});
+```
+
 ## Installation
 
 ```sh

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

@@ -1,5 +1,25 @@
 # babel-plugin-transform-es2015-modules-commonjs
 
+> This plugin transforms ES2015 modules to [CommonJS](http://wiki.commonjs.org/wiki/Modules/1.1).
+
+## Example
+
+**In**
+
+```javascript
+export default 42;
+```
+
+**Out**
+
+```javascript
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+
+exports.default = 42;
+```
+
 ## Installation
 
 ```sh
@@ -41,3 +61,27 @@ require("babel-core").transform("code", {
   plugins: ["transform-es2015-modules-commonjs"]
 });
 ```
+
+## Options `loose`
+
+As per the spec, `import` and `export` are only allowed to be used at the top
+level. When in loose mode these are allowed to be used anywhere.
+
+And by default, when using exports with babel a non-enumerable `__esModule` property
+is exported.
+
+```javascript
+var foo = exports.foo = 5;
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+```
+
+In environments that don't support this you can enable loose mode on `es6.modules`
+and instead of using `Object.defineProperty` an assignment will be used instead.
+
+```javascript
+var foo = exports.foo = 5;
+exports.__esModule = true;
+```

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

@@ -1,5 +1,28 @@
 # babel-plugin-transform-es2015-modules-systemjs
 
+> This plugin transforms ES2015 modules to [SystemJS](https://github.com/systemjs/systemjs).
+
+## Example
+
+**In**
+
+```javascript
+export default 42;
+```
+
+**Out**
+
+```javascript
+System.register([], function (_export, _context) {
+  return {
+    setters: [],
+    execute: function () {
+      _export("default", 42);
+    }
+  };
+});
+```
+
 ## Installation
 
 ```sh

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

@@ -1,5 +1,41 @@
 # babel-plugin-transform-es2015-modules-umd
 
+> This plugin transforms ES2015 modules to [Universal Module Definition (UMD)](https://github.com/umdjs/umd).
+
+## Example
+
+**In**
+
+```javascript
+export default 42;
+```
+
+**Out**
+
+```javascript
+(function (global, factory) {
+  if (typeof define === "function" && define.amd) {
+    define(["exports"], factory);
+  } else if (typeof exports !== "undefined") {
+    factory(exports);
+  } else {
+    var mod = {
+      exports: {}
+    };
+    factory(mod.exports);
+    global.actual = mod.exports;
+  }
+})(this, function (exports) {
+  "use strict";
+
+  Object.defineProperty(exports, "__esModule", {
+    value: true
+  });
+
+  exports.default = 42;
+});
+```
+
 ## Installation
 
 ```sh

packages/babel-plugin-transform-es2015-object-super/README.md

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-object-super
 
-Compile ES2015 object super to ES5
+> Compile ES2015 object super to ES5
 
 ## Installation
 

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

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-parameters
 
-Compile ES2015 default and rest parameters to ES5
+> Compile ES2015 default and rest parameters to ES5
 
 ## Installation
 
@@ -8,6 +8,12 @@ Compile ES2015 default and rest parameters to ES5
 npm install --save-dev babel-plugin-transform-es2015-parameters
 ```
 
+## Caveats
+
+Default parameters desugar into `let` declarations to retain proper semantics. If this is
+not supported in your environment then you'll need the
+[transform-block-scoping](/docs/plugins/transform-es2015-block-scoping) plugin.
+
 ## Usage
 
 ### Via `.babelrc` (Recommended)

packages/babel-plugin-transform-es2015-shorthand-properties/README.md

@@ -1,6 +1,40 @@
 # babel-plugin-transform-es2015-shorthand-properties
 
-Compile ES2015 shorthand properties to ES5
+> Compile ES2015 shorthand properties to ES5
+
+## Example
+
+**In**
+
+```js
+var o = { a, b, c };
+```
+
+**Out**
+
+```js
+var o = { a: a, b: b, c:c };
+```
+
+**In**
+
+```js
+var cat = {
+  getName() {
+    return name;
+  }
+};
+```
+
+**Out**
+
+```js
+var cat = {
+  getName: function () {
+    return name;
+  }
+};
+```
 
 ## Installation
 

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

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-spread
 
-Compile ES2015 spread to ES5
+> Compile ES2015 spread to ES5
 
 ## Installation
 
@@ -43,3 +43,7 @@ require("babel-core").transform("code", {
   plugins: ["transform-es2015-spread"]
 });
 ```
+
+## Options
+
+* `loose` - All iterables are assumed to be arrays.

packages/babel-plugin-transform-es2015-sticky-regex/README.md

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-sticky-regex
 
-Compile ES2015 sticky regex to an ES5 RegExp constructor
+> Compile ES2015 sticky regex to an ES5 RegExp constructor
 
 ## Installation
 

packages/babel-plugin-transform-es2015-template-literals/README.md

@@ -1,6 +1,20 @@
 # babel-plugin-transform-es2015-template-literals
 
-Compile ES2015 template literals to ES5
+> Compile ES2015 template literals to ES5
+
+## Example
+
+**In**
+
+```javascript
+`foo${bar}`;
+```
+
+**Out**
+
+```javascript
+"foo" + bar;
+```
 
 ## Installation
 
@@ -44,3 +58,24 @@ require("babel-core").transform("code", {
   plugins: ["transform-es2015-template-literals"]
 });
 ```
+
+## Options
+
+### `loose`
+In loose mode, tagged template literal objects aren't frozen.
+
+
+### `spec`
+This option wraps all template literal expressions with `String`. See [babel/babel#1065](https://github.com/babel/babel/issues/1065) for more info.
+
+**In**
+
+```javascript
+`foo${bar}`;
+```
+
+**Out**
+
+```javascript
+"foo" + String(bar);
+```

packages/babel-plugin-transform-es2015-typeof-symbol/README.md

@@ -1,5 +1,25 @@
 # babel-plugin-transform-es2015-typeof-symbol
 
+> ES6 introduces a new native type called [symbols](/docs/learn-es6#symbols). This transformer wraps all `typeof` expressions with a method that replicates native behaviour. (ie. returning "symbol" for symbols)
+
+## Example
+
+**In**
+
+```javascript
+typeof Symbol() === "symbol";
+```
+
+**Out**
+
+```javascript
+var _typeof = function (obj) {
+  return obj && obj.constructor === Symbol ? "symbol" : typeof obj;
+};
+
+_typeof(Symbol()) === "symbol";
+```
+
 ## Installation
 
 ```sh

packages/babel-plugin-transform-es2015-unicode-regex/README.md

@@ -1,6 +1,6 @@
 # babel-plugin-transform-es2015-unicode-regex
 
-Compile ES2015 unicode regex to ES5
+> Compile ES2015 unicode regex to ES5
 
 ## Installation