Docs: Improve gulp.watch API with Chokidar specifics

docs/API.md

@@ -493,6 +493,9 @@ A task name, a function or an array of either.
 ### gulp.watch(glob[, opts], fn)
 
 Watch files and do something when a file changes.
+File watching is provided by the [`chokidar`][chokidar] module.
+Please report any file watching problems directly to its
+[issue tracker](https://github.com/paulmillr/chokidar/issues).
 
 ```js
 gulp.watch('js/**/*.js', gulp.parallel('uglify', 'reload'));
@@ -509,7 +512,23 @@ A single glob or array of globs that indicate which files to watch for changes.
 #### opts
 Type: `Object`
 
-Options, that are passed to [`chokidar`][chokidar].
+Options that are passed to [`chokidar`][chokidar].
+
+Commonly used options:
+* `ignored` ([anymatch](https://github.com/es128/anymatch)-compatible definition)
+Defines files/paths to be excluded from being watched.
+* `usePolling` (boolean, default: `false`). When `true` uses a watch method backed
+by stat polling. Usually necessary when watching files on a network mount or on a
+VMs file system.
+* `cwd` (path string). The base directory from which watch paths are to be
+derived. Paths emitted with events will be relative to this.
+* `alwaysStat` (boolean, default: `false`). If relying upon the
+[`fs.Stats`](http://nodejs.org/api/fs.html#fs_class_fs_stats) object
+that may get passed as a second argument with `add`, `addDir`, and `change` events
+when available, set this to `true` to ensure it is provided with every event. May
+have a slight performance penalty.
+
+Read about the full set of options in [`chokidar`'s README][chokidar]
 
 #### fn
 Type: `Function`
@@ -518,15 +537,13 @@ An [async](#async-support) function to run when a file changes.
 
 `gulp.watch` returns a wrapped [chokidar] FSWatcher object. If provided,
 the callback will be triggered upon any `add`, `change`, or `unlink` event.
-Listeners can also be set directly for any of [chokidar]'s events.
+Listeners can also be set directly for any of [chokidar]'s events, such as
+`addDir`, `unlinkDir`, and `error`.
 
 ```js
 var watcher = gulp.watch('js/**/*.js', gulp.parallel('uglify', 'reload'));
 watcher.on('change', function(path, stats) {
   console.log('File ' + path + ' was changed');
-  if (stats) {
-    console.log('changed size to ' + stats.size);
-  }
 });
 
 watcher.on('unlink', function(path) {
@@ -544,7 +561,22 @@ Type: Object
 
 [File stats](http://nodejs.org/api/fs.html#fs_class_fs_stats) object when available.
 Setting the `alwaysStat` option to true will ensure that a file stat object will be
-available.
+provided.
+
+#### watcher methods
+
+##### watcher.close()
+
+Shuts down the file watcher.
+
+##### watcher.add(glob)
+
+Watch additional glob (or array of globs) with an already-running watcher instance.
+
+##### watcher.unwatch(glob)
+
+Stop watching a glob (or array of globs) while leaving the watcher running and
+emitting events for the remaining paths it is watching.
 
 ### gulp.tree(options)