Add stub Ruby commands for all Bash commands.

This gets us pretty similar (but easier to manage) manpage output but
much nicer completions etc. for all these commands.

Library/Homebrew/abstract_command.rb

@@ -32,6 +32,12 @@ def command_name
              .delete_suffix("-cmd")
       end
 
+      sig { void }
+      def raise_sh_command_error!
+        raise StandardError, "This command is just here for completions generation. " \
+                             "It's actually defined in `cmd/#{command_name}` instead."
+      end
+
       # @return the AbstractCommand subclass associated with the brew CLI command name.
       sig { params(name: String).returns(T.nilable(T.class_of(AbstractCommand))) }
       def command(name) = subclasses.find { _1.command_name == name }

Library/Homebrew/cmd/--repository.rb

@@ -3,9 +3,6 @@
 
 require "abstract_command"
 
-# This Ruby command exists to allow generation of completions for the Bash
-# version.
-# It is not meant to be run.
 module Homebrew
   module Cmd
     class Repository < AbstractCommand
@@ -20,16 +17,10 @@ def self.command_name = "--repository"
         EOS
 
         named_args :tap
-
-        hide_from_man_page!
       end
 
       sig { override.void }
-      def run
-        raise StandardError,
-              "This command is just here for completions generation. " \
-              "It's actually defined in `cmd/--repository.sh` instead."
-      end
+      def run = raise_sh_command_error!
     end
   end
 end

Library/Homebrew/cmd/--repository.sh

@@ -1,8 +1,4 @@
-#:  * `--repository`, `--repo` [<tap> ...]
-#:
-#:  Display where Homebrew's Git repository is located.
-#:
-#:  If <user>`/`<repo> are provided, display where tap <user>`/`<repo>'s directory is located.
+# Documentation defined in Library/Homebrew/cmd/--repository.rb
 
 # HOMEBREW_REPOSITORY, HOMEBREW_LIBRARY are set by brew.sh
 # shellcheck disable=SC2154

Library/Homebrew/cmd/--version.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+
+module Homebrew
+  module Cmd
+    class Version < AbstractCommand
+      sig { override.returns(String) }
+      def self.command_name = "--version"
+
+      cmd_args do
+        description <<~EOS
+          Print the version numbers of Homebrew, Homebrew/homebrew-core and
+          Homebrew/homebrew-cask (if tapped) to standard output.
+        EOS
+      end
+
+      sig { override.void }
+      def run = raise_sh_command_error!
+    end
+  end
+end

Library/Homebrew/cmd/--version.sh

@@ -1,6 +1,4 @@
-#:  * `--version`, `-v`
-#:
-#:  Print the version numbers of Homebrew, Homebrew/homebrew-core and Homebrew/homebrew-cask (if tapped) to standard output.
+# Documentation defined in Library/Homebrew/cmd/--version.rb
 
 # HOMEBREW_CORE_REPOSITORY, HOMEBREW_CASK_REPOSITORY, HOMEBREW_VERSION are set by brew.sh
 # shellcheck disable=SC2154

Library/Homebrew/cmd/casks.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+
+# This Ruby command exists to allow generation of completions for the Bash
+# version. It is not meant to be run.
+module Homebrew
+  module Cmd
+    class Casks < AbstractCommand
+      cmd_args do
+        description "List all locally installable casks including short names."
+      end
+
+      sig { override.void }
+      def run = raise_sh_command_error!
+    end
+  end
+end

Library/Homebrew/cmd/casks.sh

@@ -1,7 +1,4 @@
-#:  * `casks`
-#:
-#:  List all locally installable casks including short names.
-#:
+# Documentation defined in Library/Homebrew/cmd/casks.rb
 
 # HOMEBREW_LIBRARY is set in bin/brew
 # shellcheck disable=SC2154

Library/Homebrew/cmd/formulae.rb

@@ -0,0 +1,17 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+
+module Homebrew
+  module Cmd
+    class Formulae < AbstractCommand
+      cmd_args do
+        description "List all locally installable formulae including short names."
+      end
+
+      sig { override.void }
+      def run = raise_sh_command_error!
+    end
+  end
+end

Library/Homebrew/cmd/formulae.sh

@@ -1,7 +1,4 @@
-#:  * `formulae`
-#:
-#:  List all locally installable formulae including short names.
-#:
+# Documentation defined in Library/Homebrew/cmd/formulae.rb
 
 # HOMEBREW_LIBRARY is set by bin/brew
 # shellcheck disable=SC2154

Library/Homebrew/cmd/setup-ruby.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+
+module Homebrew
+  module Cmd
+    class SetupRuby < AbstractCommand
+      cmd_args do
+        description <<~EOS
+          Installs and configures Homebrew's Ruby. If `command` is passed, it will only run Bundler if necessary for that command.
+        EOS
+
+        named_args :command
+      end
+
+      sig { override.void }
+      def run = raise_sh_command_error!
+    end
+  end
+end

Library/Homebrew/cmd/setup-ruby.sh

@@ -1,9 +1,4 @@
-#:  * `setup-ruby [command]`
-#:
-#:  Installs and configures Homebrew's Ruby.
-#:  If `command` is passed, it will only run Bundler if necessary for that
-#:  command.
-#:
+# Documentation defined in Library/Homebrew/cmd/setup-ruby.rb
 
 # HOMEBREW_LIBRARY is set by brew.sh
 # HOMEBREW_BREW_FILE is set by extend/ENV/super.rb

Library/Homebrew/cmd/shellenv.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+
+module Homebrew
+  module Cmd
+    class Shellenv < AbstractCommand
+      cmd_args do
+        description <<~EOS
+          Valid shells: bash|csh|fish|pwsh|sh|tcsh|zsh
+
+          Print export statements. When run in a shell, this installation of Homebrew will be added to your `PATH`, `MANPATH`, and `INFOPATH`.
+
+          The variables `HOMEBREW_PREFIX`, `HOMEBREW_CELLAR` and `HOMEBREW_REPOSITORY` are also exported to avoid querying them multiple times.
+          To help guarantee idempotence, this command produces no output when Homebrew's `bin` and `sbin` directories are first and second
+          respectively in your `PATH`. Consider adding evaluation of this command's output to your dotfiles (e.g. `~/.bash_profile` or
+          `~/.zprofile` on macOS and `~/.bashrc` or `~/.zshrc` on Linux) with: `eval "$(brew shellenv)"`
+
+          The shell can be specified explicitly with a supported shell name parameter. Unknown shells will output POSIX exports.
+        EOS
+        named_args :shell
+      end
+
+      sig { override.void }
+      def run = raise_sh_command_error!
+    end
+  end
+end

Library/Homebrew/cmd/shellenv.sh

@@ -1,13 +1,4 @@
-#:  * `shellenv [bash|csh|fish|pwsh|sh|tcsh|zsh]`
-#:
-#:  Print export statements. When run in a shell, this installation of Homebrew will be added to your `PATH`, `MANPATH`, and `INFOPATH`.
-#:
-#:  The variables `HOMEBREW_PREFIX`, `HOMEBREW_CELLAR` and `HOMEBREW_REPOSITORY` are also exported to avoid querying them multiple times.
-#:  To help guarantee idempotence, this command produces no output when Homebrew's `bin` and `sbin` directories are first and second
-#:  respectively in your `PATH`. Consider adding evaluation of this command's output to your dotfiles (e.g. `~/.bash_profile` or
-#:  `~/.zprofile` on macOS and `~/.bashrc` or `~/.zshrc` on Linux) with: `eval "$(brew shellenv)"`
-#:
-#:  The shell can be specified explicitly with a supported shell name parameter. Unknown shells will output POSIX exports.
+# Documentation defined in Library/Homebrew/cmd/shellenv.rb
 
 # HOMEBREW_CELLAR and HOMEBREW_PREFIX are set by extend/ENV/super.rb
 # HOMEBREW_REPOSITORY is set by bin/brew

Library/Homebrew/cmd/update-reset.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+
+module Homebrew
+  module Cmd
+    class UpdateReset < AbstractCommand
+      cmd_args do
+        description <<~EOS
+          Fetch and reset Homebrew and all tap repositories (or any specified <repository>) using `git`(1) to their latest `origin/HEAD`.
+
+          *Note:* this will destroy all your uncommitted or committed changes.
+        EOS
+
+        named_args :tap
+      end
+
+      sig { override.void }
+      def run = raise_sh_command_error!
+    end
+  end
+end

Library/Homebrew/cmd/update-reset.sh

@@ -1,8 +1,4 @@
-#:  * `update-reset` [<path-to-tap-repository> ...]
-#:
-#:  Fetch and reset Homebrew and all tap repositories (or any specified <repository>) using `git`(1) to their latest `origin/HEAD`.
-#:
-#:  *Note:* this will destroy all your uncommitted or committed changes.
+# Documentation defined in Library/Homebrew/cmd/update-reset.rb
 
 # Replaces the function in Library/Homebrew/brew.sh to cache the Git executable to provide
 # speedup when using Git repeatedly and prevent errors if the shim changes mid-update.

Library/Homebrew/cmd/update.rb

@@ -0,0 +1,31 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+
+module Homebrew
+  module Cmd
+    class Update < AbstractCommand
+      cmd_args do
+        description <<~EOS
+          Fetch the newest version of Homebrew and all formulae from GitHub using `git`(1) and perform any necessary migrations.
+        EOS
+        switch "--merge",
+               description: "Use `git merge` to apply updates (rather than `git rebase`)."
+        switch "--auto-update",
+               description: "Run on auto-updates (e.g. before `brew install`). Skips some slower steps."
+        switch "-f", "--force",
+               description: "Always do a slower, full update check (even if unnecessary)."
+        switch "-q", "--quiet",
+               description: "Make some output more quiet."
+        switch "-v", "--verbose",
+               description: "Print the directories checked and `git` operations performed."
+        switch "-d", "--debug",
+               description: "Display a trace of all shell commands as they are executed."
+      end
+
+      sig { override.void }
+      def run = raise_sh_command_error!
+    end
+  end
+end

Library/Homebrew/cmd/update.sh

@@ -1,14 +1,4 @@
-#:  * `update` [<options>]
-#:
-#:  Fetch the newest version of Homebrew and all formulae from GitHub using `git`(1) and perform any necessary migrations.
-#:
-#:        --merge                      Use `git merge` to apply updates (rather than `git rebase`).
-#:        --auto-update                Run on auto-updates (e.g. before `brew install`). Skips some slower steps.
-#:    -f, --force                      Always do a slower, full update check (even if unnecessary).
-#:    -q, --quiet                      Make some output more quiet.
-#:    -v, --verbose                    Print the directories checked and `git` operations performed.
-#:    -d, --debug                      Display a trace of all shell commands as they are executed.
-#:    -h, --help                       Show this message.
+# Documentation defined in Library/Homebrew/cmd/update.rb
 
 # HOMEBREW_CURLRC, HOMEBREW_DEVELOPER, HOMEBREW_GIT_EMAIL, HOMEBREW_GIT_NAME
 # HOMEBREW_UPDATE_CLEANUP, HOMEBREW_UPDATE_TO_TAG are from the user environment

Library/Homebrew/cmd/vendor-install.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+
+module Homebrew
+  module Cmd
+    class VendorInstall < AbstractCommand
+      cmd_args do
+        description <<~EOS
+          Install Homebrew's portable Ruby.
+        EOS
+
+        named_args :target
+
+        hide_from_man_page!
+      end
+
+      sig { override.void }
+      def run = raise_sh_command_error!
+    end
+  end
+end

Library/Homebrew/cmd/vendor-install.sh

@@ -1,7 +1,4 @@
-#:  @hide_from_man_page
-#:  * `vendor-install` [<target>]
-#:
-#:  Install Homebrew's portable Ruby.
+# Documentation defined in Library/Homebrew/cmd/vendor-install.rb
 
 # HOMEBREW_CURLRC, HOMEBREW_LIBRARY is from the user environment
 # HOMEBREW_CACHE, HOMEBREW_CURL, HOMEBREW_LINUX, HOMEBREW_LINUX_MINIMUM_GLIBC_VERSION, HOMEBREW_MACOS,

Library/Homebrew/dev-cmd/rubocop.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+
+module Homebrew
+  module Cmd
+    class Rubocop < AbstractCommand
+      cmd_args do
+        description <<~EOS
+          Installs, configures and runs Homebrew's `rubocop`.
+        EOS
+      end
+
+      sig { override.void }
+      def run = raise_sh_command_error!
+    end
+  end
+end

Library/Homebrew/dev-cmd/rubocop.sh

@@ -1,6 +1,4 @@
-#:  * `rubocop`
-#:
-#:  Installs, configures and runs Homebrew's `rubocop`.
+# Documentation defined in Library/Homebrew/dev-cmd/rubocop.rb
 
 # HOMEBREW_LIBRARY is from the user environment.
 # HOMEBREW_RUBY_PATH is set by utils/ruby.sh