Revert "Revert "help: print cli/parser help message if used""

Library/Homebrew/brew.rb

@@ -95,7 +95,7 @@ begin
   if (empty_argv || help_flag) && cmd != "cask"
     require "help"
     Homebrew::Help.help cmd, empty_argv: empty_argv
-    # `Homebrew.help` never returns, except for external/unknown commands.
+    # `Homebrew.help` never returns, except for unknown commands.
   end
 
   if internal_cmd

Library/Homebrew/cli/parser.rb

@@ -16,6 +16,22 @@ module Homebrew
         new(args, &block).parse(args)
       end
 
+      def self.from_cmd_path(cmd_path)
+        cmd_method_prefix = cmd_path.basename(cmd_path.extname)
+                                    .to_s
+                                    .sub(/^brew-/, "")
+                                    .tr("-", "_")
+        cmd_args_method_name = "#{cmd_method_prefix}_args".to_sym
+
+        begin
+          Homebrew.send(cmd_args_method_name) if require?(cmd_path)
+        rescue NoMethodError => e
+          raise if e.name != cmd_args_method_name
+
+          nil
+        end
+      end
+
       def self.global_options
         {
           quiet:   [["-q", "--quiet"], :quiet, "Suppress any warnings."],
@@ -159,7 +175,8 @@ module Homebrew
       end
 
       def generate_help_text
-        @parser.to_s.sub(/^/, "#{Tty.bold}Usage: brew#{Tty.reset} ")
+        @parser.to_s
+               .sub(/^/, "#{Tty.bold}Usage: brew#{Tty.reset} ")
                .gsub(/`(.*?)`/m, "#{Tty.bold}\\1#{Tty.reset}")
                .gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) }
                .gsub(/<(.*?)>/m, "#{Tty.underline}\\1#{Tty.reset}")

Library/Homebrew/dev-cmd/man.rb

@@ -4,8 +4,6 @@ require "formula"
 require "erb"
 require "ostruct"
 require "cli/parser"
-# Require all commands
-Dir.glob("#{HOMEBREW_LIBRARY_PATH}/{dev-,}cmd/*.rb").sort.each { |cmd| require cmd }
 
 module Homebrew
   module_function
@@ -151,19 +149,13 @@ module Homebrew
     # preserve existing manpage order
     cmd_paths.sort_by(&method(:sort_key_for_path))
              .each do |cmd_path|
-      cmd_args_method_name = cmd_arg_parser(cmd_path)
-
-      cmd_man_page_lines = begin
-        cmd_parser = Homebrew.send(cmd_args_method_name)
+      cmd_man_page_lines = if cmd_parser = CLI::Parser.from_cmd_path(cmd_path)
         next if cmd_parser.hide_from_man_page
 
         cmd_parser_manpage_lines(cmd_parser).join
-      rescue NoMethodError => e
-        raise if e.name != cmd_args_method_name
-
-        nil
+      else
+        cmd_comment_manpage_lines(cmd_path)
       end
-      cmd_man_page_lines ||= cmd_comment_manpage_lines(cmd_path)
 
       man_page_lines << cmd_man_page_lines
     end
@@ -171,10 +163,6 @@ module Homebrew
     man_page_lines.compact.join("\n")
   end
 
-  def cmd_arg_parser(cmd_path)
-    "#{cmd_path.basename.to_s.gsub(".rb", "").tr("-", "_")}_args".to_sym
-  end
-
   def cmd_parser_manpage_lines(cmd_parser)
     lines = [format_usage_banner(cmd_parser.usage_banner_text)]
     lines += cmd_parser.processed_options.map do |short, long, _, desc|

Library/Homebrew/help.rb

@@ -72,37 +72,31 @@ module Homebrew
       # Resume execution in `brew.rb` for unknown commands.
       return if path.nil?
 
-      # Display help for internal command (or generic help if undocumented).
+      # Display help for commands (or generic help if undocumented).
       puts command_help(path)
       exit 0
     end
 
     def command_help(path)
-      # Let OptionParser generate help text for commands which have a parser defined
-      cmd = path.basename(path.extname)
-      cmd_args_method_name = "#{cmd.to_s.tr("-", "_")}_args".to_sym
-      begin
-        return Homebrew.send(cmd_args_method_name)
-                       .generate_help_text
-      rescue NoMethodError => e
-        raise if e.name != cmd_args_method_name
-
-        nil
+      # Let OptionParser generate help text for commands which have a parser
+      if cmd_parser = CLI::Parser.from_cmd_path(path)
+        return cmd_parser.generate_help_text
       end
 
+      # Otherwise read #: lines from the file.
       help_lines = command_help_lines(path)
-      if help_lines.empty?
+      if help_lines.blank?
         opoo "No help text in: #{path}" if ARGV.homebrew_developer?
-        HOMEBREW_HELP
-      else
-        Formatter.wrap(help_lines.join.gsub(/^  /, ""), COMMAND_DESC_WIDTH)
-                 .sub("@hide_from_man_page ", "")
-                 .sub(/^\* /, "#{Tty.bold}Usage: brew#{Tty.reset} ")
-                 .gsub(/`(.*?)`/m, "#{Tty.bold}\\1#{Tty.reset}")
-                 .gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) }
-                 .gsub(/<(.*?)>/m, "#{Tty.underline}\\1#{Tty.reset}")
-                 .gsub(/\*(.*?)\*/m, "#{Tty.underline}\\1#{Tty.reset}")
+        return HOMEBREW_HELP
       end
+
+      Formatter.wrap(help_lines.join.gsub(/^  /, ""), COMMAND_DESC_WIDTH)
+               .sub("@hide_from_man_page ", "")
+               .sub(/^\* /, "#{Tty.bold}Usage: brew#{Tty.reset} ")
+               .gsub(/`(.*?)`/m, "#{Tty.bold}\\1#{Tty.reset}")
+               .gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) }
+               .gsub(/<(.*?)>/m, "#{Tty.underline}\\1#{Tty.reset}")
+               .gsub(/\*(.*?)\*/m, "#{Tty.underline}\\1#{Tty.reset}")
     end
   end
 end

Library/Homebrew/utils.rb

@@ -498,7 +498,10 @@ module Kernel
   end
 
   def command_help_lines(path)
-    path.read.lines.grep(/^#:/).map { |line| line.slice(2..-1) }
+    path.read
+        .lines
+        .grep(/^#:/)
+        .map { |line| line.slice(2..-1) }
   end
 
   def redact_secrets(input, secrets)