docs(plugins): clean up and improve plugin documentation (#1254)

Add lead-in descriptions and clean up content. Document the concept 
and range of the limit-chunk-count-plugin.

Resolves #1161 (combined with @simon04's work)
Resolves #815

Author: skipjack

content/plugins/commons-chunk-plugin.md

@@ -7,12 +7,12 @@ contributors:
   - kevinzwhuang
 ---
 
+The `CommonsChunkPlugin` is an opt-in feature that creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points. By separating common modules from bundles, the resulting chunked file can be loaded once initially, and stored in cache for later use. This results in pagespeed optimizations as the browser can quickly serve the shared code from cache, rather than being forced to load a larger bundle whenever a new page is visited.
+
 ```javascript
 new webpack.optimize.CommonsChunkPlugin(options)
 ```
 
-The `CommonsChunkPlugin` is an opt-in feature that creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points. By separating common modules from bundles, the resulting chunked file can be loaded once initially, and stored in cache for later use. This results in pagespeed optimizations as the browser can quickly serve the shared code from cache, rather than being forced to load a larger bundle whenever a new page is visited.
-
 
 ## Options
 

content/plugins/context-replacement-plugin.md

@@ -2,6 +2,9 @@
 title: ContextReplacementPlugin
 contributors:
   - simon04
+related:
+  - title: Issue #2783 - ContextReplacementPlugin Description
+  - url: https://github.com/webpack/webpack/issues/2783#issuecomment-234137265
 ---
 
 *Context* refers to a [require with an expression](/guides/dependency-management/#require-with-expression) such as `require('./locale/' + name + '.json')`. When encountering such an expression, webpack infers the directory (`'./locale/'`) and a regular expression (`/^.*\.json$/`). Since the `name` is not known at compile time, webpack includes every file as module in the bundle.
@@ -20,7 +23,7 @@ new webpack.ContextReplacementPlugin(
 )
 ```
 
-If the resource (directory) matches `resourceRegExp`, the plugin replaces the default resource, recursive flag or generated regular expression with `newContentResource`, `newContentRecursive` or `newContextRegExp` respectively. If `newContentResource` is relative, it is resolved relative to the previous resource. 
+If the resource (directory) matches `resourceRegExp`, the plugin replaces the default resource, recursive flag or generated regular expression with `newContentResource`, `newContentRecursive` or `newContextRegExp` respectively. If `newContentResource` is relative, it is resolved relative to the previous resource.
 
 **Example**
 
@@ -74,8 +77,3 @@ new ContextReplacementPlugin(/selector/, './folder', {
   /* runtime-request: compile-time request */
 })
 ```
-
-
-## References
-
-* https://github.com/webpack/webpack/issues/2783#issuecomment-234137265

content/plugins/define-plugin.md

@@ -5,13 +5,25 @@ contributors:
   - rouzbeh84
 ---
 
+The `DefinePlugin` allows you to create global constants which can be configured at **compile** time. This can be useful for allowing different behavior between development builds and release builds. If you perform logging in your development build but not in the release build you might use a global constant to determine whether logging takes place. That's where `DefinePlugin` shines, set it and forget it rules for development and release builds.
+
 ``` javascript
-new webpack.DefinePlugin(definitions)
+new webpack.DefinePlugin({
+  // Definitions...
+})
 ```
 
-The `DefinePlugin` allows you to create global constants which can be configured at **compile** time. This can be useful for allowing different behavior between development builds and release builds. If you perform logging in your development build but not in the release build you might use a global constant to determine whether logging takes place. That's where `DefinePlugin` shines, set it and forget it rules for development and release builds.
 
-**Example:**
+## Usage
+
+Each key passed into `DefinePlugin` is an identifier or multiple identifiers joined with `.`.
+
+* If the value is a string it will be used as a code fragment.
+* If the value isn't a string, it will be stringified (including functions).
+* If the value is an object all keys are defined the same way.
+* If you prefix `typeof` to the key, it's only defined for typeof calls.
+
+The values will be inlined into the code allowing a minification pass to remove the redundant conditional.
 
 ``` javascript
 new webpack.DefinePlugin({
@@ -30,21 +42,13 @@ if(!BROWSER_SUPPORTS_HTML5) require("html5shiv");
 
 T> Note that because the plugin does a direct text replacement, the value given to it must include **actual quotes** inside of the string itself. Typically, this is done either with either alternate quotes, such as `'"production"'`, or by using `JSON.stringify('production')`.
 
-Each key passed into `DefinePlugin` is an identifier or multiple identifiers joined with `.`.
-
-* If the value is a string it will be used as a code fragment.
-* If the value isn't a string, it will be stringified (including functions).
-* If the value is an object all keys are defined the same way.
-* If you prefix `typeof` to the key, it's only defined for typeof calls.
-
-The values will be inlined into the code allowing a minification pass to remove the redundant conditional.
-
-**Example:**
+__index.js__
 
 ``` javascript
 if (!PRODUCTION) {
   console.log('Debug info')
 }
+
 if (PRODUCTION) {
   console.log('Production log')
 }
@@ -67,7 +71,8 @@ and then after a minification pass results in:
 console.log('Production log')
 ```
 
-## Use Case: Feature Flags
+
+## Feature Flags
 
 Enable/disable features in production/development build using [feature flags](https://en.wikipedia.org/wiki/Feature_toggle).
 
@@ -78,7 +83,8 @@ new webpack.DefinePlugin({
 })
 ```
 
-## Use Case: Service URLs
+
+## Service URLs
 
 Use a different service URL in production/development builds:
 

content/plugins/dll-plugin.md

@@ -11,17 +11,13 @@ related:
     url: https://github.com/webpack/webpack/tree/master/examples/explicit-vendor-chunk/README.md
 ---
 
-## Introduction
-
 The `DllPlugin` and `DllReferencePlugin` provide means to split bundles in a way that can drastically improve build time performance.
 
-[`DllPlugin`](/plugins/dll-plugin#dllplugin) is used in a separate webpack config exclusively to create a dll-only-bundle. It creates a `manifest.json` file, which is used by the [`DllReferencePlugin`](/plugins/dll-plugin#dllreferenceplugin) to map dependencies.
-
-`DllReferencePlugin` is used in the primary webpack config, it references the dll-only-bundle(s) to require pre-built dependencies.
-
 
 ## `DllPlugin`
 
+This plugin is used in a separate webpack config exclusively to create a dll-only-bundle. It creates a `manifest.json` file, which is used by the [`DllReferencePlugin`](/plugins/dll-plugin#dllreferenceplugin) to map dependencies.
+
 * `context` (optional): context of requests in the manifest file (defaults to the webpack context.)
 * `name`: name of the exposed dll function ([TemplatePaths](https://github.com/webpack/webpack/blob/master/lib/TemplatedPathPlugin.js): `[hash]` & `[name]` )
 * `path`: **absolute path** to the manifest json file (output)
@@ -35,7 +31,9 @@ Creates a `manifest.json` which is written to the given `path`. It contains mapp
 Combine this plugin with [`output.library`](/configuration/output/#output-library) option to expose (aka, put into the global scope) the dll function.
 
 
-### `DllReferencePlugin`
+## `DllReferencePlugin`
+
+This plugin is used in the primary webpack config, it references the dll-only-bundle(s) to require pre-built dependencies.
 
 * `context`: (**absolute path**) context of requests in the manifest (or content property)
 * `manifest` (object): an object containing `content` and `name`

content/plugins/ignore-plugin.md

@@ -4,18 +4,19 @@ contributors:
   - simon04
 ---
 
-```js
-new webpack.IgnorePlugin(requestRegExp, [contextRegExp])
-```
-
-Don't generate modules for requests matching the provided RegExp.
+Prevent generation of modules for `import` or `require` calls matching the following regular expressions:
 
 * `requestRegExp` A RegExp to test the request against.
 * `contextRegExp` (optional) A RegExp to test the context (directory) against.
 
-## Typical use-cases
+``` js
+new webpack.IgnorePlugin(requestRegExp, [contextRegExp])
+```
+
+The following examples demonstrate a few ways this plugin can be used.
+
 
-### Ignore moment locales
+## Ignore Moment Locales
 
 As of [moment](https://momentjs.com/) 2.18, all locales are bundled together with the core library (see [this GitHub issue](https://github.com/moment/moment/issues/2373)). You can use the `IgnorePlugin` to stop any locale being bundled with moment:
 

content/plugins/limit-chunk-count-plugin.md

@@ -2,11 +2,45 @@
 title: LimitChunkCountPlugin
 contributors:
   - rouzbeh84
+  - skipjack
 ---
 
-While writing your code, you may have already added many code split points to load stuff on demand. After compiling you might notice that there are too many chunks that are too small - creating larger HTTP overhead. Luckily, webpack can post-process your chunks by merging them. You can provide two options as _objects_:
+While writing your code, you may have already added many code split points to load stuff on demand. After compiling you might notice that some chunks are too small - creating larger HTTP overhead. Luckily, this plugin can post-process your chunks by merging them.
 
-- Limit the maximum chunk count inline with `--optimize-max-chunks 15` or in your config as `new webpack.optimize.LimitChunkCountPlugin({maxChunks: 15})`
-- Limit the minimum chunk size inline with `--optimize-min-chunk-size 10000` or in your config as `new webpack.optimize.MinChunkSizePlugin({minChunkSize: 10000})`
+``` js
+new webpack.optimize.LimitChunkCountPlugin({
+  // Options...
+})
+```
 
-webpack will take care of it by merging chunks (it will prefer merging chunk that have duplicate modules). Nothing will be merged into the entry chunk, so as not to impact initial page loading time.
+
+## Options
+
+The following options are supported:
+
+- `maxChunks`: Limit the maximum number of chunks using a value greater greater than or equal to `1`. Using `1` will prevent any additional chunks from being added as the entry/main chunk is also included in the count.
+- `minChunkSize`: Set a minimum chunk size.
+
+While merging chunks, webpack will try to identify those that have duplicate modules and merge them first. Nothing will be merged into the entry chunk, so as not to impact initial page loading time. Here's a small example:
+
+``` js
+new webpack.optimize.LimitChunkCountPlugin({
+  maxChunks: 5, // Must be greater than or equal to one
+  minChunkSize: 1000
+})
+```
+
+
+## CLI
+
+This plugin and it's options can also be invoked via the CLI:
+
+``` bash
+--optimize-max-chunks 15
+```
+
+or
+
+``` bash
+--optimize-min-chunk-size 10000
+```

content/plugins/loader-options-plugin.md

@@ -1,29 +1,37 @@
 ---
 title: LoaderOptionsPlugin
 contributors:
-    - johnnyreilly
+  - johnnyreilly
+  - skipjack
 ---
 
-?> Review this content
+The `LoaderOptionsPlugin` is unlike other plugins in that it is built for migration from webpack version 1 to version 2. In webpack v2, the schema for a `webpack.config.js` became stricter; no longer open for extension by other loaders and plugins. The intention is that you pass `options` directly to loaders and plugins (i.e. `options` are __not__ global or shared).
 
-The `LoaderOptionsPlugin` is unlike other plugins.  It exists to help people move from webpack 1 to webpack 2.  With webpack 2 the schema for a `webpack.config.js` became stricter; no longer open for extension by other loaders / plugins.  With webpack 2 the intention is that you pass `options` directly to loaders / plugins. i.e. options are **not** global / shared.
+However, until a loader has been updated to depend upon options being passed directly to them, the `LoaderOptionsPlugin` exists to bridge the gap. You can configure global loader options with this plugin and all loaders will receive these options.
 
-However, until a loader has been updated to depend upon options being passed directly to them, the `LoaderOptionsPlugin` exists to bridge the gap.  You can configure global / shared loader options with this plugin and all loaders will receive these options.
+``` js
+new webpack.LoaderOptionsPlugin({
+  // Options...
+})
+```
 
-In the future this plugin may be removed.
+W> This plugin will be removed in the future as it only exists for migration.
 
-```javascript
-new webpack.LoaderOptionsPlugin(options)
-```
+
+## Options
+
+This plugin supports the following options:
 
 * `options.debug` (`boolean`): Whether loaders should be in `debug` mode or not. `debug` will be removed as of webpack 3.
 * `options.minimize` (`boolean`): Where loaders can be switched to minimize mode.
-* `options.options` (`object`): A configuration object that can be used to configure older loaders - this will take the same schema a `webpack.config.js`
+* `options.options` (`object`): A configuration object that can be used to configure older loaders - this will take the same schema a `webpack.config.js`.
+* `options.options.context` (`string`): The context that can be used to configure older loaders.
+* any other options allowed in a `webpack.config.js`....
+
 
-* `options.options.context` (`string`): The context that can be used to configure older loaders
-* other options as in a `webpack.config.js`....
+## Usage
 
-## Examples
+Here's an example of how this plugin might be used:
 
 ```javascript
 new webpack.LoaderOptionsPlugin({

content/plugins/min-chunk-size-plugin.md

@@ -4,4 +4,10 @@ contributors:
 sort: 1
 ---
 
-Try to keep the chunk size above a limit.
+Keep chunk size above the specified limit by merging chunks that are smaller than the `minChunkSize`.
+
+``` js
+new webpack.optimize.MinChunkSizePlugin({
+  minChunkSize: 10000 // Minimum number of characters
+})
+```

content/plugins/no-emit-on-errors-plugin.md

@@ -4,12 +4,12 @@ contributors:
   - simon04
 ---
 
-```javascript
+Use the `NoEmitOnErrorsPlugin` to skip the emitting phase whenever there are errors while compiling. This ensures that no assets are emitted that include errors. The `emitted` flag in the stats is `false` for all assets.
+
+``` js
 new webpack.NoEmitOnErrorsPlugin()
 ```
 
-Use the `NoEmitOnErrorsPlugin` to skip the emitting phase whenever there are errors while compiling. This ensures that no assets are emitted that include errors. The `emitted` flag in the stats is `false` for all assets.
-
-If you are using the [CLI](/api/cli/), the webpack process will not exit with an error code by enabling this plugin. If you want webpack to "fail" when using the CLI, please check out the [`bail` option](/api/cli/#advanced-options).
+T> This supersedes the (now deprecated) webpack 1 plugin `NoErrorsPlugin`.
 
-Note: This supersedes the (now deprecated) webpack 1 plugin `NoErrorsPlugin`.
+W> If you are using the [CLI](/api/cli/), the webpack process will not exit with an error code by enabling this plugin. If you want webpack to "fail" when using the CLI, please check out the [`bail` option](/api/cli/#advanced-options).

content/plugins/normal-module-replacement-plugin.md

@@ -4,23 +4,19 @@ contributors:
   - gonzoyumo
 ---
 
-## Install
-
-The `NormalModuleReplacementPlugin` is a built-in webpack plugin.
-
-
-## Usage
-
-``` javascript
-new webpack.NormalModuleReplacementPlugin(resourceRegExp, newResource)
-```
-
 The `NormalModuleReplacementPlugin` allows you to replace resources that match `resourceRegExp` with `newResource`. If `newResource` is relative, it is resolved relative to the previous resource. If `newResource` is a function, it is expected to overwrite the request attribute of the supplied resource.
 
 This can be useful for allowing different behaviour between builds.
 
+``` js
+new webpack.NormalModuleReplacementPlugin(
+  resourceRegExp,
+  newResource
+)
+```
 
-## Basic example
+
+## Basic Example
 
 Replace a specific module when building for a [development environment](/guides/production-build).
 
@@ -36,7 +32,7 @@ new webpack.NormalModuleReplacementPlugin(
 ```
 
 
-## Advanced example
+## Advanced Example
 
 Conditional build depending on an [specified environment](/configuration/configuration-types).
 
@@ -52,7 +48,7 @@ module.exports = function(env) {
       })
     ]
   }
-  
+
 }
 ```