Cleanup description handling

Library/Homebrew/commands.rb

@@ -230,22 +230,27 @@ module Commands
     end
   end
 
-  def command_description(command)
+  def command_description(command, short: false)
     path = self.path(command)
     return if path.blank?
 
     if cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path)
+      if short
+        cmd_parser.description.split(".").first
+      else
         cmd_parser.description
+      end
     else
       comment_lines = path.read.lines.grep(/^#:/)
 
       # skip the comment's initial usage summary lines
       comment_lines.slice(2..-1)&.each do |line|
         if /^#:  (?<desc>\w.*+)$/ =~ line
+          return desc.split(".").first if short
+
           return desc
         end
       end
-      []
     end
   end
 

Library/Homebrew/completions.rb

@@ -107,6 +107,8 @@ module Homebrew
     def update_shell_completions!
       commands = Commands.commands(external: false, aliases: true).sort
 
+      puts "Writing completions to #{COMPLETIONS_DIR}"
+
       (COMPLETIONS_DIR/"bash/brew").atomic_write generate_bash_completion_file(commands)
       (COMPLETIONS_DIR/"zsh/_brew").atomic_write generate_zsh_completion_file(commands)
     end
@@ -130,7 +132,7 @@ module Homebrew
         next if option.blank?
 
         name = option.first
-        desc = format_description option.second
+        desc = option.second
         if name.start_with? "--[no-]"
           options[name.remove("[no-]")] = desc
           options[name.sub("[no-]", "no-")] = desc
@@ -197,7 +199,7 @@ module Homebrew
       options = command_options(command).sort.map do |opt, desc|
         next opt if desc.blank?
 
-        "#{opt}[#{desc}]"
+        "#{opt}[#{format_description desc}]"
       end
       if types = Commands.named_args_type(command)
         named_args_strings, named_args_types = types.partition { |type| type.is_a? String }
@@ -233,10 +235,10 @@ module Homebrew
       variables[:builtin_command_descriptions] = commands.map do |command|
         next if Commands::HOMEBREW_INTERNAL_COMMAND_ALIASES.key? command
 
-        description = Commands.command_description(command)
+        description = Commands.command_description(command, short: true)
         next if description.blank?
 
-        description = format_description description.split(".").first
+        description = format_description description
         "'#{command}:#{description}'"
       end.compact
 

Library/Homebrew/test/completions_spec.rb

@@ -154,7 +154,7 @@ describe Homebrew::Completions do
     end
 
     describe ".format_description" do
-      it "escapes single quotes for shells" do
+      it "escapes single quotes" do
         expect(described_class.format_description("Homebrew's")).to eq "Homebrew'\\''s"
       end
 
@@ -174,24 +174,24 @@ describe Homebrew::Completions do
     describe ".command_options" do
       it "returns an array of options for a ruby command" do
         expected_options = {
-          "--debug"   => "Display any debugging information",
+          "--debug"   => "Display any debugging information.",
-          "--help"    => "Show this message",
+          "--help"    => "Show this message.",
-          "--hide"    => "Act as if none of the specified hidden are installed. hidden should be " \
+          "--hide"    => "Act as if none of the specified <hidden> are installed. <hidden> should be " \
-                         "a comma-separated list of formulae",
+                         "a comma-separated list of formulae.",
-          "--quiet"   => "Make some output more quiet",
+          "--quiet"   => "Make some output more quiet.",
-          "--verbose" => "Make some output more verbose",
+          "--verbose" => "Make some output more verbose.",
         }
         expect(described_class.command_options("missing")).to eq expected_options
       end
 
       it "returns an array of options for a shell command" do
         expected_options = {
-          "--debug"      => "Display a trace of all shell commands as they are executed",
+          "--debug"      => "Display a trace of all shell commands as they are executed.",
-          "--force"      => "Always do a slower, full update check (even if unnecessary)",
+          "--force"      => "Always do a slower, full update check (even if unnecessary).",
-          "--help"       => "Show this message",
+          "--help"       => "Show this message.",
-          "--merge"      => "Use `git merge` to apply updates (rather than `git rebase`)",
+          "--merge"      => "Use `git merge` to apply updates (rather than `git rebase`).",
-          "--preinstall" => "Run on auto-updates (e.g. before `brew install`). Skips some slower steps",
+          "--preinstall" => "Run on auto-updates (e.g. before `brew install`). Skips some slower steps.",
-          "--verbose"    => "Print the directories checked and `git` operations performed",
+          "--verbose"    => "Print the directories checked and `git` operations performed.",
         }
         expect(described_class.command_options("update")).to eq expected_options
       end
@@ -211,14 +211,9 @@ describe Homebrew::Completions do
         expect(described_class.command_options("help")).to eq({})
       end
 
-      it "will list global options only once if overriden" do
+      it "will override global options with local descriptions" do
-        # count = 0
         options = described_class.command_options("upgrade")
-        # options.each_key do |opt|
+        expect(options["--verbose"]).to eq "Print the verification and postinstall steps."
-        #   count += 1 if opt == "--verbose"
-        # end
-        # expect(count).to eq 1
-        expect(options["--verbose"]).to eq "Print the verification and postinstall steps"
       end
     end