Improve documentation on devtool

src/content/configuration/devtool.md

@@ -26,53 +26,91 @@ Choose a style of [source mapping](http://blog.teamtreehouse.com/introduction-so
 
 T> The webpack repository contains an [example showing the effect of all `devtool` variants](https://github.com/webpack/webpack/tree/master/examples/source-map). Those examples will likely help you to understand the differences.
 
-devtool                       | build | rebuild | production | quality
------------------------------ | ----- | ------- | ---------- | -----------------------------
-eval                          | +++   | +++     | no         | generated code
-cheap-eval-source-map         | +     | ++      | no         | transformed code (lines only)
-cheap-source-map              | +     | o       | yes        | transformed code (lines only)
-cheap-module-eval-source-map  | o     | ++      | no         | original source (lines only)
-cheap-module-source-map       | o     | -       | yes        | original source (lines only)
-eval-source-map               | --    | +       | no         | original source
-source-map                    | --    | --      | yes        | original source
-inline-source-map             | --    | --      | no         | original source
-hidden-source-map             | --    | --      | yes        | original source
-nosources-source-map          | --    | --      | yes        | without source content
-
-T> `+` means faster, `-` slower and `o` about the same time
-
-Some of these values are suited for development and some for production. For development you typically want fast Source Maps at the cost of bundle size, but for production you want separate Source Maps that are accurate.
+T> Instead of using the `devtool` option you can also use `SourceMapDevToolPlugin`/`EvalSourceMapDevToolPlugin` directly as it has more options. Never use both the `devtool` option and plugin together. The `devtool` option adds the plugin internally so you would end up with the plugin applied twice.
+
+devtool                        | build | rebuild | production | quality
+------------------------------ | ----- | ------- | ---------- | -----------------------------
+(none)                         | +++   | +++     | no         | bundled code
+eval                           | +++   | +++     | no         | generated code
+cheap-eval-source-map          | +     | ++      | no         | transformed code (lines only)
+cheap-module-eval-source-map   | o     | ++      | no         | original source (lines only)
+eval-source-map                | --    | +       | no         | original source
+cheap-source-map               | +     | o       | no         | transformed code (lines only)
+cheap-module-source-map        | o     | -       | no         | original source (lines only)
+inline-cheap-source-map        | +     | o       | no         | transformed code (lines only)
+inline-cheap-module-source-map | o     | -       | no         | original source (lines only)
+source-map                     | --    | --      | yes        | original source
+inline-source-map              | --    | --      | no         | original source
+hidden-source-map              | --    | --      | yes        | original source
+nosources-source-map           | --    | --      | yes        | without source content
+
+T> `+++` super fast, `++` fast, `+` pretty fast, `o` medium, `-` pretty slow, `--` slow
+
+Some of these values are suited for development and some for production. For development you typically want fast Source Maps at the cost of bundle size, but for production you want separate Source Maps that are accurate and support minimizing.
 
 W> There are some issues with Source Maps in Chrome. [We need your help!](https://github.com/webpack/webpack/issues/3165).
 
 T> See [`output.sourceMapFilename`](/configuration/output#output-sourcemapfilename) to customize the filenames of generated Source Maps.
 
 
+### Qualities
+
+`bundled code` - You see all generated code as a big blob of code. You don't see modules separated from each other.
+
+`generated code` - You see each module separated from each other, annotated with module names. You see the code generated by webpack. Example: Instead of `import {test} from "module"; test();` you see something like `var module__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(42); module__WEBPACK_IMPORTED_MODULE_1__.a();`.
+
+`transformed code` - You see each module separated from each other, annotated with module names. You see the code before webpack transforms it, but after Loaders transpile it. Example: Instead of `import {test} from "module"; class A extends test {}` you see something like `import {test} from "module"; var A = function(_test) { ... }(test);`
+
+`original source` - You see each module separated from each other, annotated with module names. You see the code before transpilation, as you authored it. This depends on Loader support.
+
+`without source content` - Contents for the sources are not included in the Source Maps. Browsers usually try to load the source from the webserver or filesystem. You have to make sure to set [`output.devtoolModuleFilenameTemplate`](/configuration/output/#output-devtoolmodulefilenametemplate) correctly to match source urls.
+
+`(lines only)` - Source Maps are simplified to a single mapping per line. This usually means a single mapping per statement (assuming you author is this way). This prevents you from debugging execution on statement level and from settings breakpoints on columns of a line. Combining with minimizing is not possible as minimizers usually only emit a single line.
+
+
 ### Development
 
 The following options are ideal for development:
 
-`eval` - Each module is executed with `eval()` and `//@ sourceURL`. This is pretty fast. The main disadvantage is that it doesn't display line numbers correctly since it gets mapped to transpiled code instead of the original code.
+`eval` - Each module is executed with `eval()` and `//@ sourceURL`. This is pretty fast. The main disadvantage is that it doesn't display line numbers correctly since it gets mapped to transpiled code instead of the original code (No Source Maps from Loaders).
+
+`eval-source-map` - Each module is executed with `eval()` and a SourceMap is added as a DataUrl to the `eval()`. Initially it is slow, but it provides fast rebuild speed and yields real files. Line numbers are correctly mapped since it gets mapped to the original code. It yields the best quality SourceMaps for development.
+
+`cheap-eval-source-map` - Similar to `eval-source-map`, each module is executed with `eval()`. It is "cheap" because it doesn't have column mappings, it only maps line numbers. It ignores SourceMaps from Loaders and only display transpiled code similar to the `eval` devtool.
+
+`cheap-module-eval-source-map` - Similar to `cheap-eval-source-map`, however, in this case Source Maps from Loaders are processed for better results. However Loader Source Maps are simplified to a single mapping per line.
+
+### Special cases
+
+The following options are not ideal for development nor production. They are needed for some special cases, i. e. for some 3rd party tools.
 
 `inline-source-map` - A SourceMap is added as a DataUrl to the bundle.
 
-`eval-source-map` - Each module is executed with `eval()` and a SourceMap is added as a DataUrl to the `eval()`. Initially it is slow, but it provides fast rebuild speed and yields real files. Line numbers are correctly mapped since it gets mapped to the original code.
+`cheap-source-map` - A SourceMap without column-mappings ignoring loader Source Maps.
 
-`cheap-eval-source-map` - Similar to `eval-source-map`, each module is executed with `eval()`. However, with this option the Source Map is passed as a Data URL to the `eval()` call. It is "cheap" because it doesn't have column mappings, it only maps line numbers.
+`inline-cheap-source-map` - Similar to `cheap-source-map` but SourceMap is added as a DataUrl to the bundle.
 
-`cheap-module-eval-source-map` - Similar to `cheap-eval-source-map`, however, in this case loaders are able to process the mapping for better results.
+`cheap-module-source-map` - A SourceMap without column-mappings that simplifies loader Source Maps to a single mapping per line.
+
+`inline-cheap-module-source-map` - Similar to `cheap-module-source-map` but SourceMap is added as a DataUrl to the bundle.
 
 
 ### Production
 
 These options are typically used in production:
 
+`(none)` (Omit the `devtool` option) - No SourceMap is emitted. This is a good option to start with.
+
 `source-map` - A full SourceMap is emitted as a separate file. It adds a reference comment to the bundle so development tools know where to find it.
 
+W> You should configure your server to disallow access to the Source Map file for normal users!
+
 `hidden-source-map` - Same as `source-map`, but doesn't add a reference comment to the bundle. Useful if you only want SourceMaps to map error stack traces from error reports, but don't want to expose your SourceMap for the browser development tools.
 
-`cheap-source-map` - A SourceMap without column-mappings ignoring loaded Source Maps.
+W> You should not deploy the Source Map file to the webserver. Instead only use it for error report tooling.
+
+`nosources-source-map` - A SourceMap is created without the `sourcesContent` in it. It can be used to map stack traces on the client without exposing all of the source code. You can deploy the Source Map file to the webserver.
 
-`cheap-module-source-map` - A SourceMap without column-mappings that simplifies loaded Source Maps to a single mapping per line.
+W> It still exposes filenames and structure for decompiling, but it doesn't expose the original code.
 
-`nosources-source-map` - A SourceMap is created without the `sourcesContent` in it. It can be used to map stack traces on the client without exposing all of the source code.
+T> When using the `uglifyjs-webpack-plugin` you must provide the `sourceMap: true` option to enable SourceMap support.