Extend documentation

docs/02-javascript-api.md

@@ -12,6 +12,8 @@ On a `bundle` object, you can call `bundle.generate` multiple times with differe
 
 Once you're finished with the `bundle` object, you should call `bundle.close()`, which will let plugins clean up their external processes or services via the [`closeBundle`](guide/en/#closebundle) hook.
 
+If an error occurs at either stage, it will return a Promise rejected with an Error, which you can identify via their `code` property. Besides `code` and `message`, many errors have additional properties you can use for custom reporting, see [`utils/error.ts`](https://github.com/rollup/rollup/blob/master/src/utils/error.ts) for a complete list of errors and warnings together with their codes and properties.
+
 ```javascript
 import { rollup } from 'rollup';
 

docs/999-big-list-of-options.md

@@ -370,7 +370,7 @@ Type: `(warning: RollupWarning, defaultHandler: (warning: string | RollupWarning
 
 A function that will intercept warning messages. If not supplied, warnings will be deduplicated and printed to the console. When using the [`--silent`](guide/en/#--silent) CLI option, this handler is the only way to get notified about warnings.
 
-The function receives two arguments: the warning object and the default handler. Warnings objects have, at a minimum, a `code` and a `message` property, allowing you to control how different kinds of warnings are handled. Other properties are added depending on the type of warning.
+The function receives two arguments: the warning object and the default handler. Warnings objects have, at a minimum, a `code` and a `message` property, allowing you to control how different kinds of warnings are handled. Other properties are added depending on the type of warning. See [`utils/error.ts`](https://github.com/rollup/rollup/blob/master/src/utils/error.ts) for a complete list of errors and warnings together with their codes and properties.
 
 ```js
 // rollup.config.js
@@ -381,7 +381,9 @@ export default {
     if (warning.code === 'UNUSED_EXTERNAL_IMPORT') return;
 
     // throw on others
-    if (warning.code === 'MISSING_EXPORT') throw new Error(warning.message);
+    // Using Object.assign over new Error(warning.message) will make the CLI
+    // print additional information such as warning location and help url.
+    if (warning.code === 'MISSING_EXPORT') throw Object.assign(new Error(), warning);
 
     // Use default for everything else
     warn(warning);

rollup.config.ts

@@ -47,7 +47,7 @@ const onwarn: WarningHandlerWithDefault = warning => {
 		'Building Rollup produced warnings that need to be resolved. ' +
 			'Please keep in mind that the browser build may never have external dependencies!'
 	);
-	throw new Error(warning.message);
+	throw Object.assign(new Error(), warning);
 };
 
 const moduleAliases = {

test/function/samples/namespace-reassign-import-fails/_config.js

@@ -2,6 +2,7 @@ const assert = require('assert');
 const path = require('path');
 const { assertIncludes } = require('../../../utils.js');
 const ID_MAIN = path.join(__dirname, 'main.js');
+const ID_FOO = path.join(__dirname, 'foo.js');
 
 module.exports = {
 	description: 'warns for reassignments to namespace exports',
@@ -13,8 +14,7 @@ module.exports = {
 		{
 			binding: 'bar',
 			code: 'MISSING_EXPORT',
-			exporter:
-				'/Users/lukastaegert/Github/rollup/test/function/samples/namespace-reassign-import-fails/foo.js',
+			exporter: ID_FOO,
 			id: ID_MAIN,
 			message: '"bar" is not exported by "foo.js", imported by "main.js".',
 			url: 'https://rollupjs.org/guide/en/#error-name-is-not-exported-by-module',