docs(API) Add error report introduction of loaders (#2231)

src/content/api/loaders.md

@@ -338,22 +338,46 @@ Should a source map be generated. Since generating source maps can be an expensi
 emitWarning(warning: Error)
 ```
 
-Emit a warning.
+Emit a warning that will be displayed in the output like the following:
 
+``` bash
+WARNING in ./src/lib.js (./src/loader.js!./src/lib.js)
+Module Warning (from ./src/loader.js):
+Here is a Warning!
+ @ ./src/index.js 1:0-25
+
+ ```
+
+T> Note that the warnings will not be displayed if `stats.warnings` is set to `false`, or some other omit setting is used to `stats` such as `none` or `errors-only`. See the [stats configuration](/configuration/stats/#stats).
 
 ### `this.emitError`
 
 ``` typescript
+
 emitError(error: Error)
+
+```
+
+Emit an error that also can be displayed in the output.
+
+``` bash
+
+ERROR in ./src/lib.js (./src/loader.js!./src/lib.js)
+Module Error (from ./src/loader.js):
+Here is an Error!
+ @ ./src/index.js 1:0-25
+
 ```
 
-Emit an error.
+T> Unlike throwing an Error directly, it will NOT interrupt compiling process of current module.
 
 
 ### `this.loadModule`
 
 ``` typescript
+
 loadModule(request: string, callback: function(err, source, sourceMap, module))
+
 ```
 
 Resolves the given request to a module, applies all configured loaders and calls back with the generated source, the sourceMap and the module instance (usually an instance of [`NormalModule`](https://github.com/webpack/webpack/blob/master/lib/NormalModule.js)). Use this function if you need to know the source code of another module to generate the result.
@@ -362,7 +386,9 @@ Resolves the given request to a module, applies all configured loaders and calls
 ### `this.resolve`
 
 ``` typescript
+
 resolve(context: string, request: string, callback: function(err, result: string))
+
 ```
 
 Resolve a request like a require expression.
@@ -371,8 +397,10 @@ Resolve a request like a require expression.
 ### `this.addDependency`
 
 ``` typescript
+
 addDependency(file: string)
 dependency(file: string) // shortcut
+
 ```
 
 Adds a file as dependency of the loader result in order to make them watchable. For example, [`html-loader`](https://github.com/webpack-contrib/html-loader) uses this technique as it finds `src` and `src-set` attributes. Then, it sets the url's for those attributes as dependencies of the html file that is parsed.
@@ -381,7 +409,9 @@ Adds a file as dependency of the loader result in order to make them watchable.
 ### `this.addContextDependency`
 
 ``` typescript
+
 addContextDependency(directory: string)
+
 ```
 
 Add a directory as dependency of the loader result.
@@ -390,7 +420,9 @@ Add a directory as dependency of the loader result.
 ### `this.clearDependencies`
 
 ``` typescript
+
 clearDependencies()
+
 ```
 
 Remove all dependencies of the loader result. Even initial dependencies and these of other loaders. Consider using `pitch`.
@@ -399,7 +431,9 @@ Remove all dependencies of the loader result. Even initial dependencies and thes
 ### `this.emitFile`
 
 ``` typescript
+
 emitFile(name: string, content: Buffer|string, sourceMap: {...})
+
 ```
 
 Emit a file. This is webpack-specific.
@@ -418,7 +452,9 @@ W> The usage of these properties is highly discouraged since we are planning to
 ### `this.exec`
 
 ``` typescript
+
 exec(code: string, filename: string)
+
 ```
 
 Execute some code fragment like a module. See [this comment](https://github.com/webpack/webpack.js.org/issues/1268#issuecomment-313513988) for a replacement method if needed.
@@ -427,7 +463,9 @@ Execute some code fragment like a module. See [this comment](https://github.com/
 ### `this.resolveSync`
 
 ``` typescript
+
 resolveSync(context: string, request: string) -> string
+
 ```
 
 Resolve a request like a require expression.
@@ -471,3 +509,95 @@ Hacky access to the Compiler object of webpack.
 ### `this._module`
 
 Hacky access to the Module object being loaded.
+
+
+## Error Reporting
+
+Here are the ways to throw an error from inside a loader:
+
+### Using `this.emitError`
+
+[this.emitError](/api/loaders/#this-emiterror) will report the errors without interrupting module's compilation.
+
+
+### Using `throw` (or other uncaught exception)
+
+Throwing an error while a loader is running will cause current module compilation failure.
+
+For example:
+
+__./src/index.js__
+
+```js
+
+require('./loader!./lib');
+
+```
+
+__./src/loader.js__
+
+```js
+
+module.exports = function(source){
+  throw new Error('Here is an fatal Error!');
+};
+
+```
+
+The module on which loader had thrown this error will get bundled like this:
+
+```js-with-links
+
+/***/ "./src/loader.js!./src/lib.js":
+/*!************************************!*\
+  !*** ./src/loader.js!./src/lib.js ***!
+  \************************************/
+/*! no static exports found */
+/***/ (function(module, exports) {
+
+throw new Error("Module build failed (from ./src/loader.js):\nError: Here is an fatal Error!\n    at Object.module.exports (/workspace/src/loader.js:3:9)");
+
+/***/ })
+
+```
+
+Then the build output will also display the error (Similar to `this.emitError`):
+
+```bash
+
+ERROR in ./src/lib.js (./src/loader.js!./src/lib.js)
+Module build failed (from ./src/loader.js):
+Error: Here is an fatal Error!
+    at Object.module.exports (/workspace/src/loader.js:2:9)
+ @ ./src/index.js 1:0-25
+
+```
+
+As you can see below, not only error message, but also details about which loader and module are involved:
+
+- the module path: `ERROR in ./src/lib.js`
+- the request string: `(./src/loader.js!./src/lib.js)`
+- the loader path: `(from ./src/loader.js)`
+- the caller path: `@ ./src/index.js 1:0-25`
+
+W> The loader path in the error is displayed since webpack 4.12
+
+### Using `callback` (in async mode)
+
+Pass an error to the callback.
+
+__./src/loader.js__
+
+```js
+
+module.exports = function(source){
+  const callback = this.async();
+  //...
+  callback(new Error('Here is an Error!'), source);
+};
+
+```
+
+Same as using throw, it will also cause module compilation failure and get an error module in the bundle.
+
+T> All the errors and warnings will be recorded into `stats`. Please see [Stats Data](/api/stats/#errors-and-warnings).