From cebddf27ce1d799c9b6e3a3e1566ced212ef618f Mon Sep 17 00:00:00 2001
From: Lindsay-Needs-Sleep
 <51773923+Lindsay-Needs-Sleep@users.noreply.github.com>
Date: Mon, 14 Oct 2019 01:26:04 -0600
Subject: [PATCH] Improve reporter documentation for mocha in browser. (#4026)

You can pass the constructor function of your custom reporter in options and mocha will use it.
# Conflicts:
#	docs/index.md
---
 docs/index.md | 42 +++++++++++++++++++++++++++---------------
 lib/mocha.js  |  2 +-
 2 files changed, 28 insertions(+), 16 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index c7be25d934..3cf7c7c143 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -868,17 +868,16 @@ Configuration
   --package  Path to package.json for config                            [string]
 
 File Handling
-  --ignore, --exclude              Ignore file(s) or glob pattern(s)
+  --file               Specify file(s) to be loaded prior to root suite
+                       execution                       [array] [default: (none)]
+  --ignore, --exclude  Ignore file(s) or glob pattern(s)
                                                        [array] [default: (none)]
   --extension, --watch-extensions  File extension(s) to load and/or watch
-                                                           [array] [default: js]
-  --file                           Specify file(s) to be loaded prior to root
-                                   suite execution     [array] [default: (none)]
-  --recursive                      Look for tests in subdirectories    [boolean]
-  --require, -r                    Require module      [array] [default: (none)]
-  --sort, -S                       Sort test files                     [boolean]
-  --watch, -w                      Watch files in the current working directory
-                                   for changes                         [boolean]
+  --recursive          Look for tests in subdirectories                [boolean]
+  --require, -r        Require module                  [array] [default: (none)]
+  --sort, -S           Sort test files                                 [boolean]
+  --watch, -w          Watch files in the current working directory for changes
+                                                                       [boolean]
 
 Test Filters
   --fgrep, -f   Only run tests containing this string                   [string]
@@ -1095,7 +1094,7 @@ Files having this extension will be considered test files. Defaults to `js`.
 
 Affects `--watch` behavior.
 
-Specifying `--extension` will _remove_ `.js` as a test file extension; use `--extension js` to re-add it. For example, to load `.mjs` and `.js` test files, you must supply `--extension mjs --extension js`.
+The option can be given multiple times. The option accepts a comma-delimited list: `--extension a,b` is equivalent to `--extension a --extension b`
 
 ### `--file <file|directory|glob>`
 
@@ -1107,6 +1106,8 @@ Files specified this way are not affected by `--sort` or `--recursive`.
 
 Files specified in this way should contain one or more suites, tests or hooks. If this is not the case, consider `--require` instead.
 
+### `--ignore <file|directory|glob>, --exclude <file|directory|glob>,`
+
 ### `--recursive`
 
 When looking for test files, recurse into subdirectories.
@@ -1132,6 +1133,8 @@ Sort test files (by absolute path) using [Array.prototype.sort][mdn-array-sort].
 
 ### `--watch, -w`
 
+Rerun tests on file changes.
+
 Executes tests on changes to JavaScript in the current working directory (and once initially).
 
 By default, only files with extension `.js` are watched. Use `--extension` to change this behavior.
@@ -1545,23 +1548,32 @@ mocha.setup({
   ui: 'tdd'
 });
 
-// Use "tdd" interface, ignore leaks, and force all tests to be asynchronous
+// Use "tdd" interface, check global leaks, and force all tests to be asynchronous
 mocha.setup({
   ui: 'tdd',
-  ignoreLeaks: true,
+  checkLeaks: true,
   asyncOnly: true
 });
 ```
 
 ### Browser-specific Option(s)
 
-The following option(s) _only_ function in a browser context:
+Browser Mocha supports many, but not all [cli options](#command-line-usage).  
+To use a [cli option](#command-line-usage) that contains a "-", please convert the option to camel-case, (eg. `check-leaks` to `checkLeaks`).
+
+#### Options that differ slightly from [cli options](#command-line-usage):
+
+`reporter` _{string|constructor}_  
+You can pass a reporter's name or a custom reporter's constructor. You can find **recommended** reporters for the browser [here](#reporting). It is possible to use [built-in reporters](#reporters) as well. Their employment in browsers is neither recommended nor supported, open the console to see the test results.
+
+#### Options that _only_ function in browser context:
 
-`noHighlighting`: If set to `true`, do not attempt to use syntax highlighting on output test code.
+`noHighlighting` _{boolean}_  
+If set to `true`, do not attempt to use syntax highlighting on output test code.
 
 ### Reporting
 
-The "HTML" reporter is what you see when running Mocha in the browser. It looks like this:
+The "html" reporter is the default reporter when running Mocha in the browser. It looks like this:
 
 ![HTML test reporter](images/reporter-html.png?withoutEnlargement&resize=920,9999){:class="screenshot" lazyload="on"}
 
diff --git a/lib/mocha.js b/lib/mocha.js
index 5582324b8a..676fff5acd 100644
--- a/lib/mocha.js
+++ b/lib/mocha.js
@@ -83,7 +83,7 @@ exports.Test = require('./test');
  * @param {boolean} [options.ignoreLeaks] - Ignore global leaks?
  * @param {boolean} [options.invert] - Invert test filter matches?
  * @param {boolean} [options.noHighlighting] - Disable syntax highlighting?
- * @param {string} [options.reporter] - Reporter name.
+ * @param {string|constructor} [options.reporter] - Reporter name or constructor.
  * @param {Object} [options.reporterOption] - Reporter settings object.
  * @param {number} [options.retries] - Number of times to retry failed tests.
  * @param {number} [options.slow] - Slow threshold value.