Update and extend documentation.

docs/02-javascript-api.md

@@ -10,7 +10,7 @@ The `rollup.rollup` function receives an input options object as parameter and r
 
 On a `bundle` object, you can call `bundle.generate` multiple times with different output options objects to generate different bundles in-memory. If you directly want to write them to disk, use `bundle.write` instead.
 
-Once you're finished with the `bundle` object, you should call `bundle.close`, which will let plugins clean up their external processes or services.
+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.
 
 ```javascript
 const rollup = require('rollup');
@@ -165,7 +165,7 @@ const outputOptions = {
 
 ### rollup.watch
 
-Rollup also provides a `rollup.watch` function that rebuilds your bundle when it detects that the individual modules have changed on disk. It is used internally when you run Rollup from the command line with the `--watch` flag.
+Rollup also provides a `rollup.watch` function that rebuilds your bundle when it detects that the individual modules have changed on disk. It is used internally when you run Rollup from the command line with the `--watch` flag. Note that when using watch mode via the JavaScript API, it is your responsibility to call `event.result.close()` in response to the `BUNDLE_END` event to allow plugins to clean up resources in the [`closeBundle`](guide/en/#closebundle) hook, see below.
 
 ```js
 const rollup = require('rollup');
@@ -177,9 +177,25 @@ watcher.on('event', event => {
   // event.code can be one of:
   //   START        — the watcher is (re)starting
   //   BUNDLE_START — building an individual bundle
+  //                  * event.input will be the input options object if present
+  //                  * event.outputFiles cantains an array of the "file" or
+  //                    "dir" option values of the generated outputs
   //   BUNDLE_END   — finished building a bundle
+  //                  * event.input will be the input options object if present
+  //                  * event.outputFiles cantains an array of the "file" or
+  //                    "dir" option values of the generated outputs
+  //                  * event.duration is the build duration in milliseconds
+  //                  * event.result contains the bundle object that can be
+  //                    used to generate additional outputs by calling
+  //                    bundle.generate or bundle.write. This is especially
+  //                    important when the watch.skipWrite option is used.
+  //                  You should call "event.result.close()" once you are done
+  //                  generating outputs, or if you do not generate outputs.
+  //                  This will allow plugins to clean up resources via the
+  //                  "closeBundle" hook.
   //   END          — finished building all bundles
   //   ERROR        — encountered an error while bundling
+  //                  * event.error contains the error that was thrown
 });
 
 // stop watching

docs/05-plugin-development.md

@@ -72,9 +72,9 @@ To interact with the build process, your plugin object includes 'hooks'. Hooks a
 * `sequential`: If several plugins implement this hook, all of them will be run in the specified plugin order. If a hook is async, subsequent hooks of this kind will wait until the current hook is resolved.
 * `parallel`: If several plugins implement this hook, all of them will be run in the specified plugin order. If a hook is async, subsequent hooks of this kind will be run in parallel and not wait for the current hook.
 
-Build hooks are run during the build phase, which is triggered by `rollup.rollup(inputOptions)`. They are mainly concerned with locating, providing and transforming input files before they are processed by Rollup. The first hook of the build phase is [options](guide/en/#options), the last one is always [buildEnd](guide/en/#buildend).
+Build hooks are run during the build phase, which is triggered by `rollup.rollup(inputOptions)`. They are mainly concerned with locating, providing and transforming input files before they are processed by Rollup. The first hook of the build phase is [`options`](guide/en/#options), the last one is always [`buildEnd`](guide/en/#buildend), unless there is a build error in which case [`closeBundle`](guide/en/#closebundle) will be called after that.
 
-Additionally, in watch mode the [watchChange](guide/en/#watchchange) hook can be triggered at any time to notify a new run will be triggered once the current run has generated its outputs. Also, when watcher closes, the [closeWatcher](guide/en/#closewatcher) hook will be triggered.
+Additionally, in watch mode the [`watchChange`](guide/en/#watchchange) hook can be triggered at any time to notify a new run will be triggered once the current run has generated its outputs. Also, when watcher closes, the [`closeWatcher`](guide/en/#closewatcher) hook will be triggered.
 
 See [Output Generation Hooks](guide/en/#output-generation-hooks) for hooks that run during the output generation phase to modify the generated output.
 
@@ -251,18 +251,13 @@ Previous/Next Hook: This hook can be triggered at any time both during the build
 
 Notifies a plugin whenever rollup has detected a change to a monitored file in `--watch` mode. This hook cannot be used by output plugins. Second argument contains additional details of change event.  
 
-#### `closeBundle`
-Type: `closeBundle: () => Promise<void> | void`<br>
-Kind: `async, parallel`<br>
-Previous/Next Hook: This hook can be triggered at any time, during build errors or when `bundle.close()` is called, in which case this would be the last hook to be triggered.
-
-Can be used to clean up any external service that may be running, this hook is never run during watch mode.
-
 ### Output Generation Hooks
 
 Output generation hooks can provide information about a generated bundle and modify a build once complete. They work the same way and have the same types as [Build Hooks](guide/en/#build-hooks) but are called separately for each call to `bundle.generate(outputOptions)` or `bundle.write(outputOptions)`. Plugins that only use output generation hooks can also be passed in via the output options and therefore run only for certain outputs.
 
-The first hook of the output generation phase is [outputOptions](guide/en/#outputoptions), the last one is either [generateBundle](guide/en/#generatebundle) if the output was successfully generated via `bundle.generate(...)`, [writeBundle](guide/en/#writebundle) if the output was successfully generated via `bundle.write(...)`, or [renderError](guide/en/#rendererror) if an error occurred at any time during the output generation.
+The first hook of the output generation phase is [`outputOptions`](guide/en/#outputoptions), the last one is either [`generateBundle`](guide/en/#generatebundle) if the output was successfully generated via `bundle.generate(...)`, [`writeBundle`](guide/en/#writebundle) if the output was successfully generated via `bundle.write(...)`, or [`renderError`](guide/en/#rendererror) if an error occurred at any time during the output generation.
+
+Additionally, [`closeBundle`](guide/en/#closebundle) can be called as the very last hook, but it is the responsibility of the User to manually call [`bundle.close()`](guide/en/#rolluprollup) to trigger this. The CLI will always make sure this is the case.
 
 #### `augmentChunkHash`
 Type: `(chunkInfo: ChunkInfo) => string`<br>
@@ -291,6 +286,15 @@ Next Hook: [`renderDynamicImport`](guide/en/#renderdynamicimport) for each dynam
 
 Cf. [`output.banner/output.footer`](guide/en/#outputbanneroutputfooter).
 
+#### `closeBundle`
+Type: `closeBundle: () => Promise<void> | void`<br>
+Kind: `async, parallel`<br>
+Previous Hook: [`buildEnd`](guide/en/#buildend) if there was a build error, otherwise when [`bundle.close()`](guide/en/#rolluprollup) is called, in which case this would be the last hook to be triggered.
+
+Can be used to clean up any external service that may be running. Rollup's CLI will make sure this hook is called after each run, but it is the responsibility of users of the JavaScript API to manually call `bundle.close()` once they are done generating bundles. For that reason, any plugin relying on this feature should carefully mention this in its documentation.
+
+If a plugin wants to retain resources across builds in watch mode, they can check for [`this.meta.watchMode`](guide/en/#thismeta-rollupversion-string-watchmode-boolean) in this hook and perform the necessary cleanup for watch mode in [`closeWatcher`](guide/en/#closewatcher).
+
 #### `footer`
 Type: `string | (() => string)`<br>
 Kind: `async, parallel`<br>