Merge pull request #20479 from Homebrew/inline-docs-updates

Messaging and comment adjustments

Author: EricFromCanada

Library/Homebrew/api.rb

@@ -27,7 +27,7 @@ def self.fetch(endpoint)
         api_url = "#{HOMEBREW_API_DEFAULT_DOMAIN}/#{endpoint}"
         output = Utils::Curl.curl_output("--fail", api_url)
       end
-      raise ArgumentError, "No file found at #{Tty.underline}#{api_url}#{Tty.reset}" unless output.success?
+      raise ArgumentError, "No file found at: #{Tty.underline}#{api_url}#{Tty.reset}" unless output.success?
 
       cache[endpoint] = JSON.parse(output.stdout, freeze: true)
     rescue JSON::ParserError

Library/Homebrew/brew.sh

@@ -201,7 +201,7 @@ then
     odie <<EOS
 conflicting Homebrew wrapper configuration!
 HOMEBREW_FORCE_BREW_WRAPPER was set to ${HOMEBREW_FORCE_BREW_WRAPPER}
-but   HOMEBREW_BREW_WRAPPER was unset.
+but HOMEBREW_BREW_WRAPPER   was unset.
 
 $(bold "Ensure you run ${HOMEBREW_FORCE_BREW_WRAPPER} directly (not ${HOMEBREW_BREW_FILE})")!
 
@@ -713,8 +713,8 @@ else
   then
     message="Please update your system curl or set HOMEBREW_CURL_PATH to a newer version.
 Minimum required version: ${HOMEBREW_MINIMUM_CURL_VERSION}
-Your curl version: ${curl_name_and_version##* }
-Your curl executable: $(type -p "${HOMEBREW_CURL}")"
+       Your curl version: ${curl_name_and_version##* }
+    Your curl executable: $(type -p "${HOMEBREW_CURL}")"
 
     if [[ -z ${HOMEBREW_CURL_PATH} ]]
     then
@@ -741,8 +741,8 @@ Your curl executable: $(type -p "${HOMEBREW_CURL}")"
   then
     message="Please update your system Git or set HOMEBREW_GIT_PATH to a newer version.
 Minimum required version: ${HOMEBREW_MINIMUM_GIT_VERSION}
-Your Git version: ${major}.${minor}.${micro}.${build}
-Your Git executable: $(unset git && type -p "${HOMEBREW_GIT}")"
+        Your Git version: ${major}.${minor}.${micro}.${build}
+     Your Git executable: $(unset git && type -p "${HOMEBREW_GIT}")"
     if [[ -z ${HOMEBREW_GIT_PATH} ]]
     then
       HOMEBREW_FORCE_BREWED_GIT="1"

Library/Homebrew/cask/artifact/abstract_uninstall.rb

@@ -389,7 +389,7 @@ def uninstall_script(directives, directive_name: :script, force: false, command:
       end
 
       def uninstall_pkgutil(*pkgs, command: nil, **_)
-        ohai "Uninstalling packages with sudo; the password may be necessary:"
+        ohai "Uninstalling packages with `sudo` (which may request your password)..."
         pkgs.each do |regex|
           ::Cask::Pkg.all_matching(regex, command).each do |pkg|
             puts pkg.package_id

Library/Homebrew/cask/artifact/pkg.rb

@@ -35,7 +35,7 @@ def install_phase(**options)
       private
 
       def run_installer(command: nil, verbose: false, **_options)
-        ohai "Running installer for #{cask} with sudo; the password may be necessary."
+        ohai "Running installer for #{cask} with `sudo` (which may request your password)..."
         unless path.exist?
           pkg = path.relative_path_from(cask.staged_path)
           pkgs = Pathname.glob(cask.staged_path/"**"/"*.pkg").map { |path| path.relative_path_from(cask.staged_path) }

Library/Homebrew/cask/audit.rb

@@ -537,8 +537,8 @@ def audit_signing
             # Shell scripts cannot be signed, so we skip them
             next false if path.text_executable?
 
-            system_command("codesign",  args:         ["--verify", "-R=notarized", "--check-notarization", path],
-                                        print_stderr: false)
+            system_command("codesign", args:         ["--verify", "-R=notarized", "--check-notarization", path],
+                                       print_stderr: false)
           else
             add_error "Unknown artifact type: #{artifact.class}", location: url.location
           end

Library/Homebrew/cask/staged.rb

@@ -25,7 +25,7 @@ def set_ownership(paths, user: T.must(User.current), group: "staff")
       full_paths = remove_nonexistent(paths)
       return if full_paths.empty?
 
-      ohai "Changing ownership of paths required by #{@cask} with sudo; the password may be necessary."
+      ohai "Changing ownership of paths required by #{@cask} with `sudo` (which may request your password)..."
       @command.run!("/usr/sbin/chown", args: ["-R", "--", "#{user}:#{group}", *full_paths],
                                        sudo: true)
     end

Library/Homebrew/cmd/deps.rb

@@ -88,8 +88,8 @@ class Deps < AbstractCommand
 
       sig { override.void }
       def run
-        raise UsageError, "`brew deps --os=all` is not supported" if args.os == "all"
-        raise UsageError, "`brew deps --arch=all` is not supported" if args.arch == "all"
+        raise UsageError, "`brew deps --os=all` is not supported." if args.os == "all"
+        raise UsageError, "`brew deps --arch=all` is not supported." if args.arch == "all"
 
         os, arch = T.must(args.os_arch_combinations.first)
         eval_all = args.eval_all?

Library/Homebrew/cmd/install.rb

@@ -181,7 +181,7 @@ def run
           # `build.rb`. Instead, `hide_from_man_page` and don't do anything with
           # this argument here.
           # This odisabled should stick around indefinitely.
-          odisabled "brew install --env", "`env :std` in specific formula files"
+          odisabled "`brew install --env`", "`env :std` in specific formula files"
         end
 
         args.named.each do |name|

Library/Homebrew/cmd/services.rb

@@ -25,27 +25,27 @@ class Services < AbstractCommand
           If `sudo` is passed, operate on `/Library/LaunchDaemons` or `/usr/lib/systemd/system` (started at boot).
           Otherwise, operate on `~/Library/LaunchAgents` or `~/.config/systemd/user` (started at login).
 
-          [`sudo`] `brew services` [`list`] (`--json`) (`--debug`):
+          [`sudo`] `brew services` [`list`] [`--json`] [`--debug`]:
           List information about all managed services for the current user (or root).
           Provides more output from Homebrew and `launchctl`(1) or `systemctl`(1) if run with `--debug`.
 
-          [`sudo`] `brew services info` (<formula>|`--all`|`--json`):
+          [`sudo`] `brew services info` (<formula>|`--all`) [`--json`]:
           List all managed services for the current user (or root).
 
-          [`sudo`] `brew services run` (<formula>|`--all`|`--file=`):
+          [`sudo`] `brew services run` (<formula>|`--all`) [`--file=`]:
           Run the service <formula> without registering to launch at login (or boot).
 
-          [`sudo`] `brew services start` (<formula>|`--all`|`--file=`):
+          [`sudo`] `brew services start` (<formula>|`--all`) [`--file=`]:
           Start the service <formula> immediately and register it to launch at login (or boot).
 
-          [`sudo`] `brew services stop` (`--keep`) (`--no-wait`|`--max-wait=`) (<formula>|`--all`):
+          [`sudo`] `brew services stop` [`--keep`] [`--no-wait`|`--max-wait=`] (<formula>|`--all`):
           Stop the service <formula> immediately and unregister it from launching at login (or boot),
           unless `--keep` is specified.
 
           [`sudo`] `brew services kill` (<formula>|`--all`):
           Stop the service <formula> immediately but keep it registered to launch at login (or boot).
 
-          [`sudo`] `brew services restart` (<formula>|`--all`|`--file=`):
+          [`sudo`] `brew services restart` (<formula>|`--all`) [`--file=`]:
           Stop (if necessary) and start the service <formula> immediately and register it to launch at login (or boot).
 
           [`sudo`] `brew services cleanup`:
@@ -58,15 +58,16 @@ class Services < AbstractCommand
         flag   "--max-wait=",
                description: "Wait at most this many seconds for `stop` to finish stopping a service. " \
                             "Defaults to 60. Set this to zero (0) seconds to wait indefinitely."
-        switch "--all",
-               description: "Run <subcommand> on all services."
-        switch "--json",
-               description: "Output as JSON."
         switch "--no-wait",
                description: "Don't wait for `stop` to finish stopping the service."
         switch "--keep",
                description: "When stopped, don't unregister the service from launching at login (or boot)."
+        switch "--all",
+               description: "Run <subcommand> on all services."
+        switch "--json",
+               description: "Output as JSON."
 
+        conflicts "--all", "--file"
         conflicts "--max-wait=", "--no-wait"
 
         named_args %w[list info run start stop kill restart cleanup]
@@ -112,7 +113,7 @@ def run
         ]
         if no_named_formula_commands.include?(subcommand)
           raise UsageError, "The `#{subcommand}` subcommand does not accept a formula argument!" if formulae.present?
-          raise UsageError, "The `#{subcommand}` subcommand does not accept the --all argument!" if args.all?
+          raise UsageError, "The `#{subcommand}` subcommand does not accept the `--all` argument!" if args.all?
         end
 
         if args.file
@@ -122,22 +123,22 @@ def run
             *Homebrew::Services::Commands::Restart::TRIGGERS,
           ]
           if file_commands.exclude?(subcommand)
-            raise UsageError, "The `#{subcommand}` subcommand does not accept the --file= argument!"
-          elsif args.all?
-            raise UsageError,
-                  "The `#{subcommand}` subcommand does not accept the --all and --file= arguments at the same time!"
+            raise UsageError, "The `#{subcommand}` subcommand does not accept the `--file=` argument!"
           end
         end
 
         unless Homebrew::Services::Commands::Stop::TRIGGERS.include?(subcommand)
-          raise UsageError, "The `#{subcommand}` subcommand does not accept the --keep argument!" if args.keep?
-          raise UsageError, "The `#{subcommand}` subcommand does not accept the --no-wait argument!" if args.no_wait?
+          raise UsageError, "The `#{subcommand}` subcommand does not accept the `--keep` argument!" if args.keep?
+
+          if args.no_wait?
+            raise UsageError, "The `#{subcommand}` subcommand does not accept the `--no-wait` argument!"
+          end
           if args.max_wait
-            raise UsageError, "The `#{subcommand}` subcommand does not accept the --max-wait= argument!"
+            raise UsageError, "The `#{subcommand}` subcommand does not accept the `--max-wait=` argument!"
           end
         end
 
-        opoo "The --all argument overrides provided formula argument!" if formulae.present? && args.all?
+        opoo "The `--all` argument overrides provided formula argument!" if formulae.present? && args.all?
 
         targets = if args.all?
           if subcommand == "start"

Library/Homebrew/cmd/upgrade.rb

@@ -126,7 +126,7 @@ class UpgradeCmd < AbstractCommand
       sig { override.void }
       def run
         if args.build_from_source? && args.named.empty?
-          raise ArgumentError, "--build-from-source requires at least one formula"
+          raise ArgumentError, "`--build-from-source` requires at least one formula"
         end
 
         formulae, casks = args.named.to_resolved_formulae_to_casks