docs: add more missing option descriptions

and improve wording or formatting where necessary.

15 files changed, 66 insertions, 37 deletions

diff --git a/Library/Homebrew/cmd/--env.rb b/Library/Homebrew/cmd/--env.rb
index 90beee89c..e0a2b9f19 100644
--- a/Library/Homebrew/cmd/--env.rb
+++ b/Library/Homebrew/cmd/--env.rb
@@ -1,5 +1,11 @@
-#:  * `--env`:
-#:    Show a summary of the Homebrew build environment.
+#:  * `--env` [`--shell=`(<shell>|`auto`)|`--plain`]:
+#:    Show a summary of the Homebrew build environment as a plain list.
+#:
+#:    Pass `--shell=`<shell> to generate a list of environment variables for the
+#:    specified shell, or `--shell=auto` to detect the current shell.
+#:
+#:    If the command's output is sent through a pipe and no shell is specified,
+#:    the list is formatted for export to `bash`(1) unless `--plain` is passed.
 
 require "extend/ENV"
 require "build_environment"
diff --git a/Library/Homebrew/cmd/desc.rb b/Library/Homebrew/cmd/desc.rb
index 53291602e..ccb7e9925 100644
--- a/Library/Homebrew/cmd/desc.rb
+++ b/Library/Homebrew/cmd/desc.rb
@@ -1,11 +1,12 @@
 #:  * `desc` <formula>:
 #:    Display <formula>'s name and one-line description.
 #:
-#:  * `desc` [`-s`|`-n`|`-d`] (<text>|`/`<text>`/`):
-#:    Search both name and description (`-s`), just the names (`-n`), or just  the
-#:    descriptions (`-d`) for <text>. If <text> is flanked by slashes, it is interpreted
-#:    as a regular expression. Formula descriptions are cached; the cache is created on
-#:    the first search, making that search slower than subsequent ones.
+#:  * `desc` [`--search`|`--name`|`--description`] (<text>|`/`<text>`/`):
+#:    Search both name and description (`--search` or `-s`), just the names
+#:    (`--name` or `-n`), or just the descriptions (`--description` or `-d`) for
+#:    <text>. If <text> is flanked by slashes, it is interpreted as a regular
+#:    expression. Formula descriptions are cached; the cache is created on the
+#:    first search, making that search slower than subsequent ones.
 
 require "descriptions"
 require "cmd/search"
diff --git a/Library/Homebrew/cmd/doctor.rb b/Library/Homebrew/cmd/doctor.rb
index 5ff8aa4eb..4e439fa0a 100644
--- a/Library/Homebrew/cmd/doctor.rb
+++ b/Library/Homebrew/cmd/doctor.rb
@@ -6,7 +6,8 @@
 #:    an issue; just ignore this.
 
 # Undocumented options:
-#     -D activates debugging and profiling of the audit methods (not the same as --debug)
+#     `-D` activates debugging and profiling of the audit methods (not the same as `--debug`)
+#     `--list-checks` lists all audit methods
 
 require "diagnostic"
 
diff --git a/Library/Homebrew/cmd/gist-logs.rb b/Library/Homebrew/cmd/gist-logs.rb
index 9c0302813..630361ca2 100644
--- a/Library/Homebrew/cmd/gist-logs.rb
+++ b/Library/Homebrew/cmd/gist-logs.rb
@@ -4,6 +4,8 @@
 #:    <formula> is usually the name of the formula to install, but it can be specified
 #:    in several different ways. See [SPECIFYING FORMULAE](#specifying-formulae).
 #:
+#:    If `--with-hostname` is passed, include the hostname in the Gist.
+#:
 #:    If `--new-issue` is passed, automatically create a new issue in the appropriate
 #:    GitHub repository as well as creating the Gist.
 #:
diff --git a/Library/Homebrew/cmd/info.rb b/Library/Homebrew/cmd/info.rb
index a78159a15..1eb9fe9fe 100644
--- a/Library/Homebrew/cmd/info.rb
+++ b/Library/Homebrew/cmd/info.rb
@@ -1,8 +1,11 @@
+#:  * `info`:
+#:    Display brief statistics for your Homebrew installation.
+#:
 #:  * `info` <formula>:
 #:    Display information about <formula>.
 #:
 #:  * `info` `--github` <formula>:
-#:    Open a browser to the GitHub History page for formula <formula>.
+#:    Open a browser to the GitHub History page for <formula>.
 #:
 #:    To view formula history locally: `brew log -p <formula>`
 #:
diff --git a/Library/Homebrew/cmd/install.rb b/Library/Homebrew/cmd/install.rb
index 575dbc4b3..e1e4712ea 100644
--- a/Library/Homebrew/cmd/install.rb
+++ b/Library/Homebrew/cmd/install.rb
@@ -1,4 +1,4 @@
-#:  * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=`<compiler>] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] <formula> [<options> ...]:
+#:  * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=`<compiler>] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] [`--force`] [`--verbose`] <formula> [<options> ...]:
 #:    Install <formula>.
 #:
 #:    <formula> is usually the name of the formula to install, but it can be specified
@@ -47,6 +47,11 @@
 #:    If `--build-bottle` is passed, prepare the formula for eventual bottling
 #:    during installation.
 #:
+#:    If `--force` (or `-f`) is passed, install without checking for previously
+#:    installed keg-only or non-migrated versions
+#:
+#:    If `--verbose` (or `-v`) is passed, print the verification and postinstall steps.
+#:
 #:    Installation options specific to <formula> may be appended to the command,
 #:    and can be listed with `brew options` <formula>.
 #:
diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb
index 1f90a3ac3..482100ba2 100644
--- a/Library/Homebrew/cmd/list.rb
+++ b/Library/Homebrew/cmd/list.rb
@@ -6,7 +6,7 @@
 #:  * `list`, `ls` `--unbrewed`:
 #:    List all files in the Homebrew prefix not installed by Homebrew.
 #:
-#:  * `list`, `ls` [`--versions` [`--multiple`]] [`--pinned`] [<formulae>]:
+#:  * `list`, `ls` [`--verbose`] [`--versions` [`--multiple`]] [`--pinned`] [<formulae>]:
 #:    List the installed files for <formulae>. Combined with `--verbose`, recursively
 #:    list the contents of all subdirectories in each <formula>'s keg.
 #:
diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb
index f163212e1..97367ca1e 100644
--- a/Library/Homebrew/cmd/outdated.rb
+++ b/Library/Homebrew/cmd/outdated.rb
@@ -9,8 +9,8 @@
 #:
 #:    If `--verbose` (or `-v`) is passed, display detailed version information.
 #:
-#:    If `--json=`<version> is passed, the output will be in JSON format. The only
-#:    valid version is `v1`.
+#:    If `--json=`<version> is passed, the output will be in JSON format.
+#:    Currently the only accepted value for <version> is `v1`.
 #:
 #:    If `--fetch-HEAD` is passed, fetch the upstream repository to detect if
 #:    the HEAD installation of the formula is outdated. Otherwise, the
diff --git a/Library/Homebrew/cmd/readall.rb b/Library/Homebrew/cmd/readall.rb
index 3bde16e7e..0a581c383 100644
--- a/Library/Homebrew/cmd/readall.rb
+++ b/Library/Homebrew/cmd/readall.rb
@@ -1,9 +1,13 @@
-#:  * `readall` [tap]:
-#:    Import all formulae from specified taps (defaults to all installed taps).
+#:  * `readall` [`--aliases`] [`--syntax`] [<taps>]:
+#:    Import all formulae from specified <taps> (defaults to all installed taps).
 #:
 #:    This can be useful for debugging issues across all formulae when making
 #:    significant changes to `formula.rb`, testing the performance of loading
 #:    all formulae or to determine if any current formulae have Ruby issues.
+#:
+#:    If `--aliases` is passed, also verify any alias symlinks in each tap.
+#:
+#:    If `--syntax` is passed, also syntax-check all of Homebrew's Ruby files.
 
 require "readall"
 
diff --git a/Library/Homebrew/cmd/style.rb b/Library/Homebrew/cmd/style.rb
index 89484d67d..1f0d385de 100644
--- a/Library/Homebrew/cmd/style.rb
+++ b/Library/Homebrew/cmd/style.rb
@@ -1,19 +1,19 @@
-#:  * `style` [`--fix`] [`--display-cop-names`] [`--only-cops=`[COP1,COP2..]|`--except-cops=`[COP1,COP2..]] [<files>|<taps>|<formulae>]:
+#:  * `style` [`--fix`] [`--display-cop-names`] [`--only-cops=`<cops>|`--except-cops=`<cops>] [<files>|<taps>|<formulae>]:
 #:    Check formulae or files for conformance to Homebrew style guidelines.
 #:
-#:    <formulae> and <files> may not be combined. If both are omitted, style will run
-#:    style checks on the whole Homebrew `Library`, including core code and all
-#:    formulae.
+#:    Lists of <files>, <taps> and <formulae> may not be combined. If none are
+#:    provided, `style` will run style checks on the whole Homebrew library,
+#:    including core code and all formulae.
 #:
-#:    If `--fix` is passed, style violations will be automatically fixed using
-#:    RuboCop's `--auto-correct` feature.
+#:    If `--fix` is passed, automatically fix style violations using RuboCop's
+#:    auto-correct feature.
 #:
-#:    If `--display-cop-names` is passed, the RuboCop cop name for each violation
-#:    is included in the output.
+#:    If `--display-cop-names` is passed, include the RuboCop cop name for each
+#:    violation in the output.
 #:
-#:    If `--only-cops` is passed, only the given Rubocop cop(s)' violations would be checked.
-#:
-#:    If `--except-cops` is passed, the given Rubocop cop(s)' checks would be skipped.
+#:    Passing `--only-cops=`<cops> will check for violations of only the listed
+#:    RuboCop <cops>, while `--except-cops=`<cops> will skip checking the listed
+#:    <cops>. For either option <cops> should be a comma-separated list of cop names.
 #:
 #:    Exits with a non-zero status if any style violations are found.
 
diff --git a/Library/Homebrew/cmd/update-report.rb b/Library/Homebrew/cmd/update-report.rb
index 98823a152..055c55a84 100644
--- a/Library/Homebrew/cmd/update-report.rb
+++ b/Library/Homebrew/cmd/update-report.rb
@@ -1,5 +1,5 @@
 #: @hide_from_man_page
-#:  * `update_report`:
+#:  * `update_report` [`--preinstall`]:
 #:    The Ruby implementation of `brew update`. Never called manually.
 
 require "formula_versions"
diff --git a/Library/Homebrew/dev-cmd/audit.rb b/Library/Homebrew/dev-cmd/audit.rb
index 9d0ed3c59..da80c42ad 100644
--- a/Library/Homebrew/dev-cmd/audit.rb
+++ b/Library/Homebrew/dev-cmd/audit.rb
@@ -1,4 +1,4 @@
-#:  * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=`<method>|`--except=`<method>] [`--only-cops=`[COP1,COP2..]|`--except-cops=`[COP1,COP2..]] [<formulae>]:
+#:  * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=`<method>|`--except=`<method>] [`--only-cops=`<cops>|`--except-cops=`<cops>] [<formulae>]:
 #:    Check <formulae> for Homebrew coding style violations. This should be
 #:    run before submitting a new formula.
 #:
@@ -8,7 +8,7 @@
 #:    style checks.
 #:
 #:    If `--fix` is passed, style violations will be
-#:    automatically fixed using RuboCop's `--auto-correct` feature.
+#:    automatically fixed using RuboCop's auto-correct feature.
 #:
 #:    If `--online` is passed, additional slower checks that require a network
 #:    connection are run.
@@ -23,19 +23,19 @@
 #:    If `--display-filename` is passed, every line of output is prefixed with the
 #:    name of the file or formula being audited, to make the output easy to grep.
 #:
-#:    If `--only` is passed, only the methods named `audit_<method>` will be run.
+#:    Passing `--only=`<method> will run only the methods named `audit_<method>`,
+#:    while `--except=`<method> will skip the methods named `audit_<method>`.
+#:    For either option <method> should be a comma-separated list.
 #:
-#:    If `--except` is passed, the methods named `audit_<method>` will not be run.
-#:
-#:    If `--only-cops` is passed, only the given Rubocop cop(s)' violations would be checked.
-#:
-#:    If `--except-cops` is passed, the given Rubocop cop(s)' checks would be skipped.
+#:    Passing `--only-cops=`<cops> will check for violations of only the listed
+#:    RuboCop <cops>, while `--except-cops=`<cops> will skip checking the listed
+#:    <cops>. For either option <cops> should be a comma-separated list of cop names.
 #:
 #:    `audit` exits with a non-zero status if any errors are found. This is useful,
 #:    for instance, for implementing pre-commit hooks.
 
 # Undocumented options:
-#     -D activates debugging and profiling of the audit methods (not the same as --debug)
+#     `-D` activates debugging and profiling of the audit methods (not the same as `--debug`)
 
 require "formula"
 require "formula_versions"
diff --git a/Library/Homebrew/dev-cmd/bottle.rb b/Library/Homebrew/dev-cmd/bottle.rb
index 204e7cef9..a233dfb57 100644
--- a/Library/Homebrew/dev-cmd/bottle.rb
+++ b/Library/Homebrew/dev-cmd/bottle.rb
@@ -25,6 +25,10 @@
 #:    If `--write` is passed, write the changes to the formula file. A new
 #:    commit will then be generated unless `--no-commit` is passed.
 
+# Undocumented options:
+#     `--json` writes bottle information to a JSON file, which can be used as
+#     the argument for `--merge`.
+
 require "formula"
 require "utils/bottles"
 require "tab"
diff --git a/Library/Homebrew/dev-cmd/bump-formula-pr.rb b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
index 7da0f9321..1f44fa549 100644
--- a/Library/Homebrew/dev-cmd/bump-formula-pr.rb
+++ b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
@@ -33,6 +33,9 @@
 #:    which opens the pull request URL in a browser. Instead, output it to the
 #:    command line.
 #:
+#:    If `--quiet` is passed, don't output replacement messages or warn about
+#:    duplicate pull requests.
+#:
 #:    Note that this command cannot be used to transition a formula from a
 #:    URL-and-sha256 style specification into a tag-and-revision style
 #:    specification, nor vice versa. It must use whichever style specification
diff --git a/Library/Homebrew/dev-cmd/linkage.rb b/Library/Homebrew/dev-cmd/linkage.rb
index e4da827f2..31e9bd103 100644
--- a/Library/Homebrew/dev-cmd/linkage.rb
+++ b/Library/Homebrew/dev-cmd/linkage.rb
@@ -1,4 +1,4 @@
-#:  * `linkage` [`--test`] [`--reverse`]  <formula>:
+#:  * `linkage` [`--test`] [`--reverse`] <formula>:
 #:    Checks the library links of an installed formula.
 #:
 #:    Only works on installed formulae. An error is raised if it is run on