dev-cmd: remove --help headers and tweak docs.

Library/Homebrew/dev-cmd/audit.rb

@@ -1,40 +1,3 @@
-#:  * `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. Will exit with a non-zero status if any errors
-#:    are found, which can be useful for implementing pre-commit hooks.
-#:
-#:    If no <formulae> are provided, all of them are checked.
-#:
-#:    If `--strict` is passed, additional checks are run, including RuboCop
-#:    style checks.
-#:
-#:    If `--fix` is passed, style violations will be
-#:    automatically fixed using RuboCop's auto-correct feature.
-#:
-#:    If `--online` is passed, additional slower checks that require a network
-#:    connection are run.
-#:
-#:    If `--new-formula` is passed, various additional checks are run that check
-#:    if a new formula is eligible for Homebrew. This should be used when creating
-#:    new formulae and implies `--strict` and `--online`.
-#:
-#:    If `--display-cop-names` is passed, the RuboCop cop name for each violation
-#:    is included in the output.
-#:
-#:    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.
-#:
-#:    Specifying `--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.
-#:
-#:    Specifying `--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.
-
-# Undocumented options:
-#     `-D` activates debugging and profiling of the audit methods (not the same as `--debug`)
-
 require "formula"
 require "formula_versions"
 require "utils/curl"
@@ -53,12 +16,12 @@ module Homebrew
   def audit_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `audit` [<options>] <formulae>
+        `audit` [<options>] <formula>
 
-        Check <formulae> for Homebrew coding style violations. This should be run before
+        Check <formula> for Homebrew coding style violations. This should be run before
         submitting a new formula. Will exit with a non-zero status if any errors are
         found, which can be useful for implementing pre-commit hooks.
-        If no <formulae> are provided, all of them are checked.
+        If no <formula> are provided, all of them are checked.
       EOS
       switch "--strict",
         description: "Run additional style checks, including RuboCop style checks."
@@ -93,6 +56,9 @@ module Homebrew
       switch :debug
       conflicts "--only", "--except"
       conflicts "--only-cops", "--except-cops"
+
+      # Undocumented options:
+      # `-D` activates debugging and profiling of the audit methods (not the same as `--debug`)
     end
   end
 

Library/Homebrew/dev-cmd/bottle.rb

@@ -1,35 +1,3 @@
-#:  * `bottle` [`--verbose`] [`--no-rebuild`|`--keep-old`] [`--skip-relocation`] [`--or-later`] [`--root-url=`<URL>] [`--force-core-tap`] [`--json`] <formulae>:
-#:    Generate a bottle (binary package) from a formula that was installed with
-#:    `--build-bottle`.
-#:
-#:    If the formula specifies a rebuild version, it will be incremented in the
-#:    generated DSL. Passing `--keep-old` will attempt to keep it at its original
-#:    value, while `--no-rebuild` will remove it.
-#:
-#:    If `--verbose` (or `-v`) is passed, print the bottling commands and any warnings
-#:    encountered.
-#:
-#:    If `--skip-relocation` is passed, do not check if the bottle can be marked
-#:    as relocatable.
-#:
-#:    If `--root-url` is passed, use the specified <URL> as the root of the
-#:    bottle's URL instead of Homebrew's default.
-#:
-#:    If `--or-later` is passed, append `_or_later` to the bottle tag.
-#:
-#:    If `--force-core-tap` is passed, build a bottle even if <formula> is not
-#:    in homebrew/core or any installed taps.
-#:
-#:    If `--json` is passed, write bottle information to a JSON file, which can
-#:    be used as the argument for `--merge`.
-#:
-#:  * `bottle` `--merge` [`--keep-old`] [`--write` [`--no-commit`]] <bottle_json_files>:
-#:    Generate a bottle from a `--json` output file and print the new DSL merged
-#:    into the existing formula.
-#:
-#:    If `--write` is passed, write the changes to the formula file. A new
-#:    commit will then be generated unless `--no-commit` is passed.
-
 require "formula"
 require "utils/bottles"
 require "tab"
@@ -72,7 +40,7 @@ module Homebrew
   def bottle_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `bottle` [<options>] <formulae>
+        `bottle` [<options>] <formula>
 
         Generate a bottle (binary package) from a formula that was installed with
         `--build-bottle`.

Library/Homebrew/dev-cmd/bump-formula-pr.rb

@@ -1,46 +1,3 @@
-#:  * `bump-formula-pr` [`--devel`] [`--dry-run` [`--write`]] [`--no-audit`|`--strict`] [`--no-browse] [`--mirror=`<URL>] [`--version=`<version>] [`--message=`<message>] (`--url=`<URL> `--sha256=`<SHA-256>|`--tag=`<tag> `--revision=`<revision>) [<formula>]:
-#:    Create a pull request to update a formula with a new URL or a new tag.
-#:
-#:    If a <URL> is specified, the <SHA-256> checksum of the new download should
-#:    also be specified. A best effort to determine the <SHA-256> and <formula>
-#:    name will be made if either or both values are not supplied by the user.
-#:
-#:    If a <tag> is specified, the Git commit <revision> corresponding to that
-#:    tag must also be specified.
-#:
-#:    If `--devel` is passed, bump the development rather than stable version.
-#:    The development spec must already exist.
-#:
-#:    If `--dry-run` is passed, print what would be done rather than doing it.
-#:
-#:    If `--write` is passed along with `--dry-run`, perform a not-so-dry run by
-#:    making the expected file modifications but not taking any Git actions.
-#:
-#:    If `--no-audit` is passed, don't run `brew audit` before opening the PR.
-#:
-#:    If `--strict` is passed, run `brew audit --strict` before opening the PR.
-#:
-#:    If `--mirror=`<URL> is passed, use the value as a mirror URL.
-#:
-#:    If `--version=`<version> is passed, use the value to override the value
-#:    parsed from the URL or tag. Note that `--version=0` can be used to delete
-#:    an existing version override from a formula if it has become redundant.
-#:
-#:    If `--message=`<message> is passed, append <message> to the default PR
-#:    message.
-#:
-#:    If `--no-browse` is passed, don't pass the `--browse` argument to `hub`
-#:    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:* this command cannot be used to transition a formula from a
-#:    URL-and-SHA-256 style specification into a tag-and-revision style
-#:    specification, nor vice versa. It must use whichever style specification
-#:    the preexisting formula already uses.
-
 require "formula"
 require "cli_parser"
 

Library/Homebrew/dev-cmd/create.rb

@@ -1,24 +1,3 @@
-#:  * `create` [`--autotools`|`--cmake`|`--meson`] [`--no-fetch`] [`--set-name` <name>] [`--set-version` <version>] [`--tap` <user>`/`<repo>] <URL>:
-#:    Generate a formula for the downloadable file at <URL> and open it in the editor.
-#:    Homebrew will attempt to automatically derive the formula name
-#:    and version, but if it fails, you'll have to make your own template. The `wget`
-#:    formula serves as a simple example. For the complete API, see:
-#:    <https://www.rubydoc.info/github/Homebrew/brew/master/Formula>
-#:
-#:    If `--autotools` is passed, create a basic template for an Autotools-style build.
-#:    If `--cmake` is passed, create a basic template for a CMake-style build.
-#:    If `--meson` is passed, create a basic template for a Meson-style build.
-#:
-#:    If `--no-fetch` is passed, Homebrew will not download <URL> to the cache and
-#:    will thus not add the SHA-256 to the formula for you, nor will it check
-#:    the GitHub API for GitHub projects (to fill out its description and homepage).
-#:
-#:    The options `--set-name` and `--set-version` each take an argument and allow
-#:    you to explicitly set the name and version of the package you are creating.
-#:
-#:    The option `--tap` takes a tap as its argument and generates the formula in
-#:    the specified tap.
-
 require "formula"
 require "formula_creator"
 require "missing_formula"

Library/Homebrew/dev-cmd/edit.rb

@@ -1,9 +1,3 @@
-#:  * `edit`:
-#:    Open the Homebrew repository for editing.
-#:
-#:  * `edit` <formula>:
-#:    Open <formula> in the editor set by `EDITOR` or `HOMEBREW_EDITOR`.
-
 require "formula"
 require "cli_parser"
 
@@ -13,7 +7,7 @@ module Homebrew
   def edit_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `edit` [<formulae>]
+        `edit` [<formula>]
 
         Open a formula in the editor set by `EDITOR` or `HOMEBREW_EDITOR`, or open the
         Homebrew repository for editing if no <formula> is provided.

Library/Homebrew/dev-cmd/extract.rb

@@ -1,15 +1,3 @@
-#:  * `extract` [`--force`] <formula> <tap> [`--version=`<version>]:
-#:    Look through repository history to find the most recent version of <formula> and
-#:    create a copy in <tap>`/Formula/`<formula>`@`<version>`.rb`. If the tap is
-#:    not installed yet, attempt to install/clone the tap before continuing.
-#:
-#:    If `--force` is passed, the file at the destination will be overwritten
-#:    if it already exists. Otherwise, existing files will be preserved.
-#:
-#:    If an argument is passed through `--version`, <version> of <formula>
-#:    will be extracted and placed in the destination tap. Otherwise, the most
-#:    recent version that can be found will be used.
-
 require "cli_parser"
 require "utils/git"
 require "formulary"

Library/Homebrew/dev-cmd/formula.rb

@@ -1,6 +1,3 @@
-#:  * `formula` <formulae>:
-#:    Display the path where a formula is located.
-
 require "formula"
 require "cli_parser"
 
@@ -10,7 +7,7 @@ module Homebrew
   def formula_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `formula` <formulae>
+        `formula` <formula>
 
         Display the path where a formula is located.
       EOS

Library/Homebrew/dev-cmd/irb.rb

@@ -1,11 +1,3 @@
-#:  * `irb` [`--examples`] [`--pry`]:
-#:    Enter the interactive Homebrew Ruby shell.
-#:
-#:    If `--examples` is passed, several examples will be shown.
-#:
-#:    If `--pry` is passed or `HOMEBREW_PRY` is set, Pry will be
-#:    used instead of IRB.
-
 require "cli_parser"
 
 class Symbol

Library/Homebrew/dev-cmd/linkage.rb

@@ -1,15 +1,3 @@
-#:  * `linkage` [`--test`] [`--reverse`] [<formulae>]:
-#:    Check the library links for kegs of installed formulae.
-#:    Raises an error if run on uninstalled formulae.
-#:
-#:    If `--test` is passed, only display missing libraries and exit with a
-#:    non-zero status if any missing libraries are found.
-#:
-#:    If `--reverse` is passed, for every library that a keg references,
-#:    print its dylib path followed by the binaries that link to it.
-#:
-#:    If <formulae> are given, check linkage for only the specified brews.
-
 require "cache_store"
 require "linkage_checker"
 require "cli_parser"
@@ -20,7 +8,7 @@ module Homebrew
   def linkage_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `linkage` [<options>] [<formulae>]
+        `linkage` [<options>] [<formula>]
 
         Check the library links for kegs of installed formulae.
         Raises an error if run on uninstalled formulae.

Library/Homebrew/dev-cmd/man.rb

@@ -1,12 +1,3 @@
-#:  * `man` [`--fail-if-changed`]:
-#:    Generate Homebrew's manpages.
-#:
-#:    If `--fail-if-changed` is passed, the command will return a failing
-#:    status code if changes are detected in the manpage outputs.
-#:    This can be used for CI to be notified when the manpages are out of date.
-#:    Additionally, the date used in new manpages will match those in the existing
-#:    manpages (to allow comparison without factoring in the date).
-
 require "formula"
 require "erb"
 require "ostruct"

Library/Homebrew/dev-cmd/mirror.rb

@@ -1,7 +1,3 @@
-#: @hide_from_man_page
-#:  * `mirror` <formulae>:
-#:    Reuploads the stable URL for a formula to Bintray to use it as a mirror.
-
 require "cli_parser"
 
 module Homebrew
@@ -10,12 +6,13 @@ module Homebrew
   def mirror_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `mirror` <formulae>
+        `mirror` <formula>
 
         Reuploads the stable URL for a formula to Bintray to use it as a mirror.
       EOS
       switch :verbose
       switch :debug
+      hide_from_man_page!
     end
   end
 

Library/Homebrew/dev-cmd/prof.rb

@@ -1,19 +1,12 @@
-#:  * `prof` [<ruby options>]:
-#:    Run Homebrew with the Ruby profiler.
-#:
-#:    *Example:* `brew prof readall`
-
 module Homebrew
   module_function
 
   def prof_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `prof` [<ruby options>]
+        `prof` <command>
 
-        Run Homebrew with the Ruby profiler.
+        Run Homebrew with the Ruby profiler e.g. `brew prof readall`.
-
-        *Example:* `brew prof readall`
       EOS
     end
   end

Library/Homebrew/dev-cmd/pull.rb

@@ -1,52 +1,3 @@
-#:  * `pull` [`--bottle`] [`--bump`] [`--clean`] [`--ignore-whitespace`] [`--resolve`] [`--branch-okay`] [`--no-pbcopy`] [`--no-publish`] [`--warn-on-publish-failure`] [`--bintray-org=`<bintray-org>] [`--test-bot-user=`<test-bot-user>] <patch-source> [<patch-source>]:
-#:    Get a patch from a GitHub commit or pull request and apply it to Homebrew.
-#:    Optionally, publish updated bottles for the formulae changed by the patch.
-#:
-#:    Each <patch-source> may be one of:
-#:
-#:      ~ The ID number of a PR (pull request) in the homebrew/core GitHub
-#:        repository
-#:
-#:      ~ The URL of a PR on GitHub, using either the web page or API URL
-#:        formats. In this form, the PR may be on Homebrew/brew,
-#:        Homebrew/homebrew-core or any tap.
-#:
-#:      ~ The URL of a commit on GitHub
-#:
-#:      ~ A "https://jenkins.brew.sh/job/..." string specifying a testing job ID
-#:
-#:    If `--bottle` is passed, handle bottles, pulling the bottle-update
-#:    commit and publishing files on Bintray.
-#:
-#:    If `--bump` is passed, for one-formula PRs, automatically reword
-#:    commit message to our preferred format.
-#:
-#:    If `--clean` is passed, do not rewrite or otherwise modify the
-#:    commits found in the pulled PR.
-#:
-#:    If `--ignore-whitespace` is passed, silently ignore whitespace
-#:    discrepancies when applying diffs.
-#:
-#:    If `--resolve` is passed, when a patch fails to apply, leave in
-#:    progress and allow user to resolve, instead of aborting.
-#:
-#:    If `--branch-okay` is passed, do not warn if pulling to a branch
-#:    besides master (useful for testing).
-#:
-#:    If `--no-pbcopy` is passed, do not copy anything to the system
-#:    clipboard.
-#:
-#:    If `--no-publish` is passed, do not publish bottles to Bintray.
-#:
-#:    If `--warn-on-publish-failure` was passed, do not exit if there's a
-#:    failure publishing bottles on Bintray.
-#:
-#:    If `--bintray-org=`<bintray-org> is passed, publish at the provided Bintray
-#:    organisation.
-#:
-#:    If `--test-bot-user=`<test-bot-user> is passed, pull the bottle block
-#:    commit from the provided user on GitHub.
-
 require "net/http"
 require "net/https"
 require "json"
@@ -74,23 +25,13 @@ module Homebrew
   def pull_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `pull` [<options>] <patch sources>
+        `pull` [<options>] <patch>
 
         Get a patch from a GitHub commit or pull request and apply it to Homebrew.
         Optionally, publish updated bottles for the formulae changed by the patch.
 
-        Each <patch source> may be one of:
+        Each <patch> may be the number of a PR in homebrew/core, the URL of a PR
-
+        on GitHub, the URL of a commit on GitHub or a "https://jenkins.brew.sh/job/..." testing job URL.
-          ~ The ID number of a PR (pull request) in the homebrew/core GitHub
-            repository
-
-          ~ The URL of a PR on GitHub, using either the web page or API URL
-            formats. In this form, the PR may be on Homebrew/brew,
-            Homebrew/homebrew-core or any tap.
-
-          ~ The URL of a commit on GitHub
-
-          ~ A "https://jenkins.brew.sh/job/..." string specifying a testing job ID
       EOS
       switch "--bottle",
         description: "Handle bottles, pulling the bottle-update commit and publishing files on Bintray."

Library/Homebrew/dev-cmd/release-notes.rb

@@ -1,10 +1,3 @@
-#:  * `release-notes` [`--markdown`] [<previous_tag>] [<end_ref>]:
-#:    Print the merged pull requests on Homebrew/brew between two Git refs.
-#:    If no <previous_tag> is provided it defaults to the latest tag.
-#:    If no <end_ref> is provided it defaults to `origin/master`.
-#:
-#:    If `--markdown` is passed, print as a Markdown list.
-
 require "cli_parser"
 
 module Homebrew

Library/Homebrew/dev-cmd/ruby.rb

@@ -1,8 +1,3 @@
-#:  * `ruby` [<ruby options>]:
-#:    Run a Ruby instance with Homebrew's libraries loaded.
-#:
-#:    *Example:* `brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb`
-
 require "cli_parser"
 
 module Homebrew
@@ -11,11 +6,10 @@ module Homebrew
   def ruby_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `ruby` [<ruby options>]
+        `ruby` [`-e`]:
 
-        Run a Ruby instance with Homebrew's libraries loaded.
+        Run a Ruby instance with Homebrew's libraries loaded e.g.
-
+        `brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb`
-        *Example:* `brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb`
       EOS
       switch "-e",
         description: "Execute the provided string argument as a script."

Library/Homebrew/dev-cmd/tap-new.rb

@@ -1,6 +1,3 @@
-#:  * `tap-new` <user>`/`<repo>:
-#:    Generate the template files for a new tap.
-
 require "tap"
 require "cli_parser"
 

Library/Homebrew/dev-cmd/test.rb

@@ -1,23 +1,8 @@
-#:  * `test` [`--devel`|`--HEAD`] [`--debug`] [`--keep-tmp`] <formulae>:
-#:    Run the test method provided by a formula.
-#:    There is no standard output or return code, but generally it should notify the
-#:    user if something is wrong with the installed formula.
-#:
-#:    To test the development or head version of a formula, use `--devel` or
-#:    `--HEAD`.
-#:
-#:    If `--debug` (or `-d`) is passed and the test fails, an interactive debugger will be
-#:    launched with access to IRB or a shell inside the temporary test directory.
-#:
-#:    If `--keep-tmp` is passed, the temporary files created for the test are
-#:    not deleted.
-#:
-#:    *Example:* `brew install jruby && brew test jruby`
-
 require "extend/ENV"
 require "formula_assertions"
 require "sandbox"
 require "timeout"
+require "cli_parser"
 
 module Homebrew
   module_function
@@ -25,7 +10,7 @@ module Homebrew
   def test_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `test` [<options>] <formulae>
+        `test` [<options>] <formula>
 
         Run the test method provided by an installed formula.
         There is no standard output or return code, but generally it should notify the

Library/Homebrew/dev-cmd/tests.rb

@@ -1,20 +1,3 @@
-#:  * `tests` [`--verbose`] [`--coverage`] [`--generic`] [`--no-compat`] [`--only=`<test_script>[`:`<line_number>]] [`--seed=`<seed>] [`--online`]:
-#:    Run Homebrew's unit and integration tests. If provided,
-#:    `--only=`<test_script> runs only <test_script>`_spec.rb`, and `--seed`
-#:    randomizes tests with the provided value instead of a random seed.
-#:
-#:    If `--verbose` (or `-v`) is passed, print the command that runs the tests.
-#:
-#:    If `--coverage` is passed, also generate code coverage reports.
-#:
-#:    If `--generic` is passed, only run OS-agnostic tests.
-#:
-#:    If `--no-compat` is passed, do not load the compatibility layer when
-#:    running tests.
-#:
-#:    If `--online` is passed, include tests that use the GitHub API and tests
-#:    that use any of the taps for official external commands.
-
 require "cli_parser"
 require "fileutils"
 
@@ -41,7 +24,7 @@ module Homebrew
         description: "Run only <test_script>`_spec.rb`. Appending `:`<line_number> will start at a "\
                      "specific line."
       flag   "--seed=",
-        description: "Randomize tests with the provided <value> instead of a random seed."
+        description: "Randomise tests with the provided <value> instead of a random seed."
       switch :verbose
       switch :debug
     end

Library/Homebrew/dev-cmd/update-test.rb

@@ -1,19 +1,3 @@
-#:  * `update-test` [`--commit=`<commit>] [`--before=`<date>] [`--to-tag`] [`--keep-tmp`]:
-#:    Run a test of `brew update` with a new repository clone.
-#:
-#:    If no arguments are passed, use `origin/master` as the start commit.
-#:
-#:    If `--commit=`<commit> is passed, use <commit> as the start commit.
-#:
-#:    If `--before=`<date> is passed, use the commit at <date> as the
-#:    start commit.
-#:
-#:    If `--to-tag` is passed, set `HOMEBREW_UPDATE_TO_TAG` to test updating
-#:    between tags.
-#:
-#:    If `--keep-tmp` is passed, retain the temporary directory containing
-#:    the new repository clone.
-
 require "cli_parser"
 
 module Homebrew

Library/Homebrew/dev-cmd/vendor-gems.rb

@@ -1,13 +1,10 @@
-#:  * `vendor-gems`:
-#:    Install and commit Homebrew's vendored gems.
-
 require "formula"
 require "cli_parser"
 
 module Homebrew
   module_function
 
-  def vendor_gems
+  def vendor_gems_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
         `vendor-gems`
@@ -15,7 +12,11 @@ module Homebrew
         Install and commit Homebrew's vendored gems.
       EOS
       switch :debug
-    end.parse
+    end
+  end
+
+  def vendor_gems
+    vendor_gems_args.parse
 
     Homebrew.install_bundler!