audit: Use OptionParser to generate help text

Library/Homebrew/brew.rb

@@ -73,7 +73,7 @@ begin
   # - a help flag is passed AND there is no command specified
   # - no arguments are passed
   # - if cmd is Cask, let Cask handle the help command instead
-  if (empty_argv || help_flag) && cmd != "cask"
+  if (empty_argv || help_flag) && cmd != "cask" && !internal_dev_cmd
     require "help"
     Homebrew::Help.help cmd, empty_argv: empty_argv
     # `Homebrew.help` never returns, except for external/unknown commands.

Library/Homebrew/cli_parser.rb

@@ -17,13 +17,21 @@ module Homebrew
         @constraints = []
         @conflicts = []
         instance_eval(&block)
+        post_initialize
+      end
+
+      def post_initialize
+        @parser.on_tail("-h", "--help", "Show this message") do
+          puts @parser
+          exit
+        end
       end
 
       def switch(*names, description: nil, env: nil, required_for: nil, depends_on: nil)
-        description = option_to_description(*names) if description.nil?
         global_switch = names.first.is_a?(Symbol)
-        names, env = common_switch(*names) if global_switch
-        @parser.on(*names, description) do
+        names, env, description = common_switch(*names) if global_switch
+        description = option_to_description(*names) if description.nil?
+        @parser.on(*names, *description.split("\n")) do
           enable_switch(*names)
         end
 
@@ -34,9 +42,13 @@ module Homebrew
         enable_switch(*names) if !env.nil? && !ENV["HOMEBREW_#{env.to_s.upcase}"].nil?
       end
 
+      def banner(text)
+        @parser.banner = text
+      end
+
       def comma_array(name, description: nil)
         description = option_to_description(name) if description.nil?
-        @parser.on(name, OptionParser::REQUIRED_ARGUMENT, Array, description) do |list|
+        @parser.on(name, OptionParser::REQUIRED_ARGUMENT, Array, *description.split("\n")) do |list|
           Homebrew.args[option_to_name(name)] = list
         end
       end
@@ -49,7 +61,7 @@ module Homebrew
           required = OptionParser::OPTIONAL_ARGUMENT
         end
         description = option_to_description(name) if description.nil?
-        @parser.on(name, description, required) do |option_value|
+        @parser.on(name, *description.split("\n"), required) do |option_value|
           Homebrew.args[option_to_name(name)] = option_value
         end
 
@@ -78,6 +90,10 @@ module Homebrew
         names.map { |name| name.to_s.sub(/\A--?/, "").tr("-", " ") }.max
       end
 
+      def summary
+        @parser.to_s
+      end
+
       def parse(cmdline_args)
         remaining_args = @parser.parse(cmdline_args)
         check_constraint_violations
@@ -95,10 +111,10 @@ module Homebrew
       # These are common/global switches accessible throughout Homebrew
       def common_switch(name)
         case name
-        when :quiet   then [["-q", "--quiet"], :quiet]
-        when :verbose then [["-v", "--verbose"], :verbose]
-        when :debug   then [["-d", "--debug"], :debug]
-        when :force   then [["-f", "--force"], :force]
+        when :quiet   then [["-q", "--quiet"], :quiet, "Suppress warnings."]
+        when :verbose then [["-v", "--verbose"], :verbose, "Verbose mode."]
+        when :debug   then [["-d", "--debug"], :debug, "Display debug info."]
+        when :force   then [["-f", "--force"], :force, "Override any warnings/validations."]
         else name
         end
       end

Library/Homebrew/dev-cmd/audit.rb

@@ -54,19 +54,27 @@ module Homebrew
 
   def audit
     Homebrew::CLI::Parser.parse do
-      switch      "--strict"
-      switch      "--online"
-      switch      "--new-formula"
-      switch      "--fix"
-      switch      "--display-cop-names"
-      switch      "--display-filename"
+      banner <<~EOS
+        Usage: brew audit [options] [<formulae>]
+
+        Check <formulae> for Homebrew coding style violations. This should be
+        run before submitting a new formula.
+
+        If no <formulae> are provided, all of them are checked.
+      EOS
+      switch      "--strict", description: "Run additional style checks, including Rubocop style checks."
+      switch      "--online", description: "Run additional slower style checks that require a\nnetwork connection."
+      switch      "--new-formula", description: "Run various additional style checks to determine if a new formula \nis eligible for Homebrew. This should be used when creating \nnew formula and implies --strict and --online."
+      switch      "--fix", description: "Fix style violations automatically using\nRuboCop's auto-correct feature."
+      switch      "--display-cop-names", description: "Include the RuboCop cop name for each violation\nin the output."
+      switch      "--display-filename", description: "Prefix everyline of output with name of the file or\nformula being audited, to make output easy to grep."
       switch      "-D", "--audit-debug", description: "Activates debugging and profiling"
+      comma_array "--only", description: "Passing --only=method will run only the methods named audit_method,\n`method` should be a comma-separated list."
+      comma_array "--except", description: "Passing --except=method will run only the methods named audit_method,\n`method` should be a comma-separated list."
+      comma_array "--only-cops", description: "Passing --only-cops=cops will check for violations of only the listed\nRuboCop cops. `cops` should be a comma-separated list of cop names."
+      comma_array "--except-cops", description: "Passing --except-cops=cops will skip checking the listed\nRuboCop cops violations. `cops` should be a comma-separated list of cop names."
       switch      :verbose
       switch      :debug
-      comma_array "--only"
-      comma_array "--except"
-      comma_array "--only-cops"
-      comma_array "--except-cops"
     end
 
     Homebrew.auditing = true