From 626b6aca2d83608e27ddcbc1444de63140aedfcd Mon Sep 17 00:00:00 2001 From: Eric Knibbe Date: Tue, 5 Aug 2025 12:47:04 -0400 Subject: [PATCH] RubyDoc output fixes --- Library/Homebrew/build_options.rb | 2 +- Library/Homebrew/cask/dsl.rb | 4 +- Library/Homebrew/cask/url.rb | 14 +- Library/Homebrew/dev-cmd/contributions.rb | 6 +- Library/Homebrew/download_strategy.rb | 2 +- Library/Homebrew/extend/kernel.rb | 2 +- Library/Homebrew/formula.rb | 162 +++++++++--------- Library/Homebrew/formula_cellar_checks.rb | 2 +- Library/Homebrew/formulary.rb | 6 +- Library/Homebrew/ignorable.rb | 2 +- Library/Homebrew/keg.rb | 2 +- Library/Homebrew/linkage_cache_store.rb | 2 +- .../livecheck/strategy/sourceforge.rb | 2 +- Library/Homebrew/livecheck/strategy/xml.rb | 2 +- Library/Homebrew/livecheck/strategy/yaml.rb | 2 +- Library/Homebrew/migrator.rb | 6 +- Library/Homebrew/os/mac/mach.rb | 2 +- .../requirements/macos_requirement.rb | 2 +- Library/Homebrew/rubocops/service.rb | 2 +- Library/Homebrew/rubocops/text.rb | 2 +- Library/Homebrew/service.rb | 2 +- Library/Homebrew/shims/super/cc | 2 +- Library/Homebrew/tap.rb | 2 +- Library/Homebrew/test/dev-cmd/bottle_spec.rb | 4 +- Library/Homebrew/test/dev-cmd/irb_spec.rb | 4 +- Library/Homebrew/test/utils/curl_spec.rb | 2 +- Library/Homebrew/uninstall.rb | 2 +- Library/Homebrew/yard/docstring_parser.rb | 19 +- 28 files changed, 131 insertions(+), 132 deletions(-) diff --git a/Library/Homebrew/build_options.rb b/Library/Homebrew/build_options.rb index 1baf70938e..3dff77598f 100644 --- a/Library/Homebrew/build_options.rb +++ b/Library/Homebrew/build_options.rb @@ -85,7 +85,7 @@ class BuildOptions # ### Example # # ```ruby - # args << "--some-beta" if build.head? + # args << "--some-feature" if build.stable? # ``` def stable? !head? diff --git a/Library/Homebrew/cask/dsl.rb b/Library/Homebrew/cask/dsl.rb index fdd29a2ed3..9b7767cc58 100644 --- a/Library/Homebrew/cask/dsl.rb +++ b/Library/Homebrew/cask/dsl.rb @@ -561,8 +561,8 @@ module Cask # Excludes the cask from autobump list. # - # TODO: limit this method to the official taps only (f.e. raise - # an error if `!tap.official?`) + # TODO: limit this method to the official taps only + # (e.g. raise an error if `!tap.official?`) # # @api public sig { params(because: T.any(String, Symbol)).void } diff --git a/Library/Homebrew/cask/url.rb b/Library/Homebrew/cask/url.rb index 6bc19deae8..848da0752a 100644 --- a/Library/Homebrew/cask/url.rb +++ b/Library/Homebrew/cask/url.rb @@ -42,32 +42,24 @@ module Cask extend Forwardable def_delegators :uri, :path, :scheme, :to_s + # Creates a `url` stanza. + # + # @api public sig { params( uri: T.any(URI::Generic, String), - # @api public verified: T.nilable(String), - # @api public using: T.any(T::Class[AbstractDownloadStrategy], Symbol, NilClass), - # @api public tag: T.nilable(String), - # @api public branch: T.nilable(String), - # @api public revisions: T.nilable(T::Hash[T.any(Symbol, String), String]), - # @api public revision: T.nilable(String), - # @api public trust_cert: T.nilable(T::Boolean), - # @api public cookies: T.nilable(T::Hash[String, String]), referer: T.nilable(T.any(URI::Generic, String)), - # @api public header: T.nilable(T.any(String, T::Array[String])), user_agent: T.nilable(T.any(Symbol, String)), - # @api public data: T.nilable(T::Hash[String, String]), - # @api public only_path: T.nilable(String), ).void } diff --git a/Library/Homebrew/dev-cmd/contributions.rb b/Library/Homebrew/dev-cmd/contributions.rb index 5e1ff025da..8700197174 100644 --- a/Library/Homebrew/dev-cmd/contributions.rb +++ b/Library/Homebrew/dev-cmd/contributions.rb @@ -68,10 +68,10 @@ module Homebrew users = args.user.presence || GitHub.members_by_team("Homebrew", "maintainers").keys users.each do |username| # TODO: Using the GitHub username to scan the `git log` undercounts some - # contributions as people might not always have configured their Git - # committer details to match the ones on GitHub. + # contributions as people might not always have configured their Git + # committer details to match the ones on GitHub. # TODO: Switch to using the GitHub APIs instead of `git log` if - # they ever support trailers. + # they ever support trailers. results[username] = scan_repositories(repos, username, from:) grand_totals[username] = total(results[username]) diff --git a/Library/Homebrew/download_strategy.rb b/Library/Homebrew/download_strategy.rb index d24445136f..5742a33183 100644 --- a/Library/Homebrew/download_strategy.rb +++ b/Library/Homebrew/download_strategy.rb @@ -663,7 +663,7 @@ class CurlDownloadStrategy < AbstractFileDownloadStrategy end end -# Strategy for downloading a file using homebrew's curl. +# Strategy for downloading a file using Homebrew's `curl`. # # @api public class HomebrewCurlDownloadStrategy < CurlDownloadStrategy diff --git a/Library/Homebrew/extend/kernel.rb b/Library/Homebrew/extend/kernel.rb index 4a3f9724a8..4500f1eb5e 100644 --- a/Library/Homebrew/extend/kernel.rb +++ b/Library/Homebrew/extend/kernel.rb @@ -3,7 +3,7 @@ # Contains shorthand Homebrew utility methods like `ohai`, `opoo`, `odisabled`. # TODO: move these out of `Kernel` into `Homebrew::GlobalMethods` and add -# necessary Sorbet and global Kernel inclusions. +# necessary Sorbet and global Kernel inclusions. module Kernel sig { params(env: T.nilable(String)).returns(T::Boolean) } diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index 472a025210..525fc58f9c 100644 --- a/Library/Homebrew/formula.rb +++ b/Library/Homebrew/formula.rb @@ -161,12 +161,12 @@ class Formula protected :active_spec # A symbol to indicate currently active {SoftwareSpec}. - # It's either :stable or :head + # It's either `:stable` or `:head`. # @see #active_spec sig { returns(Symbol) } attr_reader :active_spec_sym - # most recent modified time for source files + # The most recent modified time for source files. sig { returns(T.nilable(Time)) } attr_reader :source_modified_time @@ -204,7 +204,7 @@ class Formula # The {BuildOptions} or {Tab} for this {Formula}. Lists the arguments passed # and any {.option}s in the {Formula}. Note that these may differ at # different times during the installation of a {Formula}. This is annoying - # but the result of state that we're trying to eliminate. + # but is the result of state that we're trying to eliminate. sig { returns(T.any(BuildOptions, Tab)) } attr_reader :build @@ -302,8 +302,8 @@ class Formula Requirement.clear_cache end - # Ensure the given formula is installed - # This is useful for installing a utility formula (e.g. `shellcheck` for `brew style`) + # Ensure the given formula is installed. + # This is useful for installing a utility formula (e.g. `shellcheck` for `brew style`). sig { params( reason: String, @@ -474,13 +474,13 @@ class Formula :downloader, ] => :active_spec - # The Bottle object for the currently active {SoftwareSpec}. + # The {Bottle} object for the currently active {SoftwareSpec}. sig { returns(T.nilable(Bottle)) } def bottle @bottle ||= T.let(Bottle.new(self, bottle_specification), T.nilable(Bottle)) if bottled? end - # The Bottle object for given tag. + # The {Bottle} object for given tag. sig { params(tag: T.nilable(Utils::Bottles::Tag)).returns(T.nilable(Bottle)) } def bottle_for_tag(tag = nil) Bottle.new(self, bottle_specification, tag) if bottled?(tag) @@ -501,32 +501,32 @@ class Formula # @see .homepage delegate homepage: :"self.class" - # The livecheck specification for the software. + # The `livecheck` specification for the software. # @!method livecheck # @see .livecheck delegate livecheck: :"self.class" - # Is a livecheck specification defined for the software? + # Is a `livecheck` specification defined for the software? # @!method livecheck_defined? # @see .livecheck_defined? delegate livecheck_defined?: :"self.class" - # Is a livecheck specification defined for the software? + # This is a legacy alias for `#livecheck_defined?`. # @!method livecheckable? # @see .livecheckable? delegate livecheckable?: :"self.class" - # Exclude the formula from autobump list. + # Exclude the formula from the autobump list. # @!method no_autobump! # @see .no_autobump! delegate no_autobump!: :"self.class" - # Is the formula in autobump list? + # Is the formula in the autobump list? # @!method autobump? # @see .autobump? delegate autobump?: :"self.class" - # Is no_autobump! method defined? + # Is a `no_autobump!` method defined? # @!method no_autobump_defined? # @see .no_autobump_defined? delegate no_autobump_defined?: :"self.class" @@ -552,7 +552,7 @@ class Formula :network_access_allowed?, ] => :"self.class" - # Whether this formula was loaded using the formulae.brew.sh API + # Whether this formula was loaded using the formulae.brew.sh API. # @!method loaded_from_api? # @see .loaded_from_api? delegate loaded_from_api?: :"self.class" @@ -584,7 +584,7 @@ class Formula sig { returns(T::Boolean) } def versioned_formula? = name.include?("@") - # Returns any other `@`-versioned formulae names for any formula (including versioned formulae). + # Returns any other `@`-versioned formulae names for any Formula (including versioned formulae). sig { returns(T::Array[String]) } def versioned_formulae_names versioned_names = if tap @@ -685,7 +685,7 @@ class Formula # @api internal delegate deps: :active_spec - # The declared {Dependency}s for the currently active {SoftwareSpec} (i.e. including those provided by macOS) + # The declared {Dependency}s for the currently active {SoftwareSpec} (i.e. including those provided by macOS). delegate declared_deps: :active_spec # The {Requirement}s for the currently active {SoftwareSpec}. @@ -781,7 +781,7 @@ class Formula end end - # The latest prefix for this formula. Checks for {#head} and then {#stable}'s {#prefix} + # The latest prefix for this formula. Checks for {#head} and then {#stable}'s {#prefix}. sig { returns(Pathname) } def latest_installed_prefix if head && (head_version = latest_head_version) && !head_version_outdated?(head_version) @@ -793,10 +793,10 @@ class Formula end end - # The directory in the cellar that the formula is installed to. + # The directory in the Cellar that the formula is installed to. # This directory points to {#opt_prefix} if it exists and if {#prefix} is not # called from within the same formula's {#install} or {#post_install} methods. - # Otherwise, return the full path to the formula's versioned cellar. + # Otherwise, return the full path to the formula's keg (versioned Cellar path). sig { params(version: T.any(String, PkgVersion)).returns(Pathname) } def prefix(version = pkg_version) versioned_prefix = versioned_prefix(version) @@ -835,7 +835,7 @@ class Formula Keg.for(linked_keg).version end - # The parent of the prefix; the named directory in the cellar containing all + # The parent of the prefix; the named directory in the Cellar containing all # installed versions of this software. sig { returns(Pathname) } def rack = HOMEBREW_CELLAR/name @@ -1135,8 +1135,8 @@ class Formula sig { returns(Pathname) } def etc = (HOMEBREW_PREFIX/"etc").extend(InstallRenamed) - # A subdirectory of `etc` with the formula name suffixed. - # e.g. `$HOMEBREW_PREFIX/etc/openssl@1.1` + # A subdirectory of `etc` with the formula name suffixed, + # e.g. `$HOMEBREW_PREFIX/etc/openssl@1.1`. # Anything using `pkgetc.install` will not overwrite other files on # e.g. upgrades but will write a new file named `*.default`. # @@ -1152,7 +1152,7 @@ class Formula sig { returns(Pathname) } def var = HOMEBREW_PREFIX/"var" - # The directory where the formula's zsh function files should be + # The directory where the formula's `zsh` function files should be # installed. # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. @@ -1161,7 +1161,7 @@ class Formula sig { returns(Pathname) } def zsh_function = share/"zsh/site-functions" - # The directory where the formula's fish function files should be + # The directory where the formula's `fish` function files should be # installed. # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. @@ -1170,7 +1170,7 @@ class Formula sig { returns(Pathname) } def fish_function = share/"fish/vendor_functions.d" - # The directory where the formula's Bash completion files should be + # The directory where the formula's `bash` completion files should be # installed. # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. @@ -1179,7 +1179,7 @@ class Formula sig { returns(Pathname) } def bash_completion = prefix/"etc/bash_completion.d" - # The directory where the formula's zsh completion files should be + # The directory where the formula's `zsh` completion files should be # installed. # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. @@ -1188,7 +1188,7 @@ class Formula sig { returns(Pathname) } def zsh_completion = share/"zsh/site-functions" - # The directory where the formula's fish completion files should be + # The directory where the formula's `fish` completion files should be # installed. # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. @@ -1197,7 +1197,7 @@ class Formula sig { returns(Pathname) } def fish_completion = share/"fish/vendor_completions.d" - # The directory where formula's powershell completion files should be + # The directory where the formula's PowerShell completion files should be # installed. # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. @@ -1254,7 +1254,7 @@ class Formula sig { returns(Pathname) } def systemd_timer_path = (any_installed_prefix || opt_prefix)/"#{service_name}.timer" - # The service specification of the software. + # The service specification for the software. sig { returns(Homebrew::Service) } def service @service ||= T.let(Homebrew::Service.new(self, &self.class.service), T.nilable(Homebrew::Service)) @@ -1414,7 +1414,7 @@ class Formula # called or when brewing a formula. # This is optional. You can use all the vars like #{version} here. # EOS - # s += "Some issue only on older systems" if MacOS.version < :el_capitan + # s += "Some issue only on older systems" if MacOS.version < :monterey # s # end # ``` @@ -1578,7 +1578,7 @@ class Formula patches.each(&:apply) end - # Yields |self,staging| with current working directory set to the uncompressed tarball + # Yields `|self,staging|` with current working directory set to the uncompressed tarball # where staging is a {Mktemp} staging context. sig(:final) { params(fetch: T::Boolean, keep_tmp: T::Boolean, debug_symbols: T::Boolean, interactive: T::Boolean, @@ -1750,7 +1750,7 @@ class Formula def_delegators :@pin, :pinnable?, :pinned_version, :pin, :unpin - # !attr[r] pinned? + # @!attribute [r] pinned? # @api internal delegate pinned?: :@pin @@ -1786,7 +1786,7 @@ class Formula "#" end - # Standard parameters for cabal-v2 builds. + # Standard parameters for Cabal-v2 builds. # # @api public sig { returns(T::Array[String]) } @@ -1800,7 +1800,7 @@ class Formula ["--jobs=#{ENV.make_jobs}", "--max-backjumps=100000", "--install-method=copy", "--installdir=#{bin}"] end - # Standard parameters for cargo builds. + # Standard parameters for Cargo builds. # # @api public sig { @@ -1870,7 +1870,7 @@ class Formula args end - # Standard parameters for meson builds. + # Standard parameters for Meson builds. # # @api public sig { returns(T::Array[String]) } @@ -1904,10 +1904,10 @@ class Formula args end - # Standard parameters for zig builds. + # Standard parameters for Zig builds. # - # `release_mode` can be set to either `:safe`, `:fast`, or `:small` - # with `:fast` being the default value + # `release_mode` can be set to either `:safe`, `:fast` or `:small`, + # with `:fast` being the default value. # # @api public sig { @@ -2207,25 +2207,25 @@ class Formula end end - # an array of all core {Formula} names + # An array of all core {Formula} names. sig { returns(T::Array[String]) } def self.core_names CoreTap.instance.formula_names end - # an array of all tap {Formula} names + # An array of all tap {Formula} names. sig { returns(T::Array[String]) } def self.tap_names @tap_names ||= T.let(Tap.reject(&:core_tap?).flat_map(&:formula_names).sort, T.nilable(T::Array[String])) end - # an array of all tap {Formula} files + # An array of all tap {Formula} files. sig { returns(T::Array[Pathname]) } def self.tap_files @tap_files ||= T.let(Tap.reject(&:core_tap?).flat_map(&:formula_files), T.nilable(T::Array[Pathname])) end - # an array of all {Formula} names + # An array of all {Formula} names. sig { returns(T::Array[String]) } def self.names @names ||= T.let((core_names + tap_names.map do |name| @@ -2233,14 +2233,14 @@ class Formula end).uniq.sort, T.nilable(T::Array[String])) end - # an array of all {Formula} names, which the tap formulae have the fully-qualified name + # An array of all {Formula} names, which the tap formulae have as the fully-qualified name. sig { returns(T::Array[String]) } def self.full_names @full_names ||= T.let(core_names + tap_names, T.nilable(T::Array[String])) end - # an array of all {Formula} - # this should only be used when users specify `--all` to a command + # An array of each known {Formula}. + # Can only be used when users specify `--eval-all` with a command or set `HOMEBREW_EVAL_ALL=1`. sig { params(eval_all: T::Boolean).returns(T::Array[Formula]) } def self.all(eval_all: false) if !eval_all && !Homebrew::EnvConfig.eval_all? @@ -2276,7 +2276,7 @@ class Formula racks.map { |rack| rack.basename.to_s } end - # An array of all installed {Formula} + # An array of all installed {Formula}e. sig { returns(T::Array[Formula]) } def self.installed Formula.cache[:installed] ||= racks.flat_map do |rack| @@ -2293,25 +2293,25 @@ class Formula installed.select { |f| f.installed_alias_path == alias_path } end - # an array of all alias files of core {Formula} + # An array of all alias files of core {Formula}e. sig { returns(T::Array[Pathname]) } def self.core_alias_files CoreTap.instance.alias_files end - # an array of all core aliases + # An array of all core aliases. sig { returns(T::Array[String]) } def self.core_aliases CoreTap.instance.aliases end - # an array of all tap aliases + # An array of all tap aliases. sig { returns(T::Array[String]) } def self.tap_aliases @tap_aliases ||= T.let(Tap.reject(&:core_tap?).flat_map(&:aliases).sort, T.nilable(T::Array[String])) end - # an array of all aliases + # An array of all aliases. sig { returns(T::Array[String]) } def self.aliases @aliases ||= T.let((core_aliases + tap_aliases.map do |name| @@ -2319,13 +2319,13 @@ class Formula end).uniq.sort, T.nilable(T::Array[String])) end - # an array of all aliases as fully-qualified names + # An array of all aliases as fully-qualified names. sig { returns(T::Array[String]) } def self.alias_full_names @alias_full_names ||= T.let(core_aliases + tap_aliases, T.nilable(T::Array[String])) end - # Returns a list of approximately matching formula names, but not the complete match + # Returns a list of approximately matching formula names, but not the complete match. sig { params(name: String).returns(T::Array[String]) } def self.fuzzy_search(name) @spell_checker ||= T.let(DidYouMean::SpellChecker.new(dictionary: Set.new(names + full_names).to_a), @@ -2338,13 +2338,13 @@ class Formula Formulary.factory(name) end - # True if this formula is provided by Homebrew itself + # True if this formula is provided by Homebrew itself. sig { returns(T::Boolean) } def core_formula? !!tap&.core_tap? end - # True if this formula is provided by external Tap + # True if this formula is provided by an external {Tap}. sig { returns(T::Boolean) } def tap? return false unless tap @@ -2352,8 +2352,8 @@ class Formula !T.must(tap).core_tap? end - # True if this formula can be installed on this platform - # Redefined in extend/os. + # True if this formula can be installed on this platform. + # Redefined in `extend/os`. sig { returns(T::Boolean) } def valid_platform? requirements.none?(MacOSRequirement) && requirements.none?(LinuxRequirement) @@ -2376,13 +2376,15 @@ class Formula delegate env: :"self.class" - # !attr[r] conflicts + # Returns a list of {FormulaConflict} objects indicating any + # formulae that conflict with this one and why. + # # @api internal sig { returns(T::Array[FormulaConflict]) } def conflicts = T.must(self.class.conflicts) - # Returns a list of Dependency objects in an installable order, which - # means if a depends on b then b will be ordered before a in this list + # Returns a list of {Dependency} objects in an installable order, which + # means if `a` depends on `b` then `b` will be ordered before `a` in this list. # # @api internal sig { params(block: T.nilable(T.proc.params(arg0: Formula, arg1: Dependency).void)).returns(T::Array[Dependency]) } @@ -2391,7 +2393,7 @@ class Formula Dependency.expand(self, cache_key:, &block) end - # The full set of Requirements for this formula's dependency tree. + # The full set of {Requirements} for this formula's dependency tree. # # @api internal sig { params(block: T.nilable(T.proc.params(arg0: Formula, arg1: Requirement).void)).returns(Requirements) } @@ -2400,7 +2402,7 @@ class Formula Requirement.expand(self, cache_key:, &block) end - # Returns a Keg for the opt_prefix or installed_prefix if they exist. + # Returns a {Keg} for the `opt_prefix` or `installed_prefix` if they exist. # If not, return `nil`. sig { returns(T.nilable(Keg)) } def any_installed_keg @@ -2429,7 +2431,7 @@ class Formula any_installed_keg&.version end - # Returns a list of Dependency objects that are required at runtime. + # Returns a list of {Dependency} objects that are required at runtime. # # @api internal sig { params(read_from_tab: T::Boolean, undeclared: T::Boolean).returns(T::Array[Dependency]) } @@ -2953,7 +2955,7 @@ class Formula (home/".bazelrc").write "startup --output_user_root=#{home}/_bazel" end - # Returns a list of Dependency objects that are declared in the formula. + # Returns a list of {Dependency} objects that are declared in the formula. sig { returns(T::Array[Dependency]) } def declared_runtime_dependencies cache_key = "Formula#declared_runtime_dependencies" unless build.any_args_or_options? @@ -2969,7 +2971,7 @@ class Formula end end - # Returns a list of Dependency objects that are not declared in the formula + # Returns a list of {Dependency} objects that are not declared in the formula # but the formula links to. sig { returns(T::Array[Dependency]) } def undeclared_runtime_dependencies @@ -3170,7 +3172,7 @@ class Formula end end elsif !installed_prefixes.empty? && !pinned? - # If the cellar only has one version installed, don't complain + # If the rack only has one version installed, don't complain # that we can't tell which one to keep. Don't complain at all if the # only installed version is a pinned formula. opoo "Skipping #{full_name}: most recent version #{pkg_version} not installed" unless quiet @@ -3376,7 +3378,7 @@ class Formula sig { returns(T::Hash[Symbol, T::Boolean]) } def network_access_allowed = T.must(@network_access_allowed) - # Whether this formula was loaded using the formulae.brew.sh API + # Whether this formula was loaded using the formulae.brew.sh API. sig { returns(T::Boolean) } def loaded_from_api? = !!@loaded_from_api @@ -3413,7 +3415,7 @@ class Formula # `:all_of` should be used when the user must use all licenses. # `:with` should be used to specify a valid SPDX exception. # - # Add `+` to an identifier to indicate that the formulae can be + # Add `+` to an identifier to indicate that the formula can be # licensed under later versions of the same license. # # ### Examples @@ -3597,7 +3599,7 @@ class Formula sig { returns(T.nilable(Symbol)) } attr_reader :pour_bottle_only_if - # If `pour_bottle?` returns `false` the user-visible reason to display for + # If `pour_bottle?` returns `false`: the user-visible reason to display for # why they cannot use the bottle. sig { returns(T.nilable(String)) } attr_accessor :pour_bottle_check_unsatisfied_reason @@ -3657,8 +3659,9 @@ class Formula # # - `:git`, `:hg`, `:svn`, `:bzr`, `:fossil`, `:cvs`, # - `:curl` (normal file download, will also extract) + # - `:homebrew_curl` (use brewed `curl`) # - `:nounzip` (without extracting) - # - `:post` (download via an HTTP POST) + # - `:post` (download via an HTTP POST request) # # ### Examples # @@ -3766,7 +3769,7 @@ class Formula # Allows adding {.depends_on} and {Patch}es just to the {.stable} {SoftwareSpec}. # This is required instead of using a conditional. - # It is preferable to also pull the {url} and {sha256= sha256} into the block if one is added. + # It is preferable to also pull the {url} and {sha256} into the block if one is added. # # ### Example # @@ -3794,7 +3797,7 @@ class Formula # If called as a method this provides just the {url} for the {SoftwareSpec}. # If a block is provided you can also add {.depends_on} and {Patch}es just to the {.head} {SoftwareSpec}. # The download strategies (e.g. `:using =>`) are the same as for {url}. - # `master` is the default branch and doesn't need stating with a `branch:` parameter. + # `master` is the default branch for Git and doesn't need stating with a `branch:` parameter. # # ### Example # @@ -4228,10 +4231,10 @@ class Formula @livecheck.instance_eval(&block) end - # Method that excludes the formula from the autobump list. + # Exclude the formula from the autobump list. # - # TODO: limit this method to the official taps only (f.e. raise - # an error if `!tap.official?`) + # TODO: limit this method to the official taps only + # (e.g. raise an error if `!tap.official?`) # # @api public sig { params(because: T.any(String, Symbol)).void } @@ -4245,17 +4248,17 @@ class Formula @autobump = T.let(false, T.nilable(T::Boolean)) end - # Is the formula in autobump list? + # Is the formula in the autobump list? sig { returns(T::Boolean) } def autobump? @autobump != false # @autobump may be `nil` end - # Is no_autobump! method defined? + # Is a `no_autobump!` method defined? sig { returns(T::Boolean) } def no_autobump_defined? = @no_autobump_defined == true - # Message that explains why the formula was excluded from autobump list. + # Message that explains why the formula was excluded from the autobump list. # Returns `nil` if no message is specified. # # @see .no_autobump! @@ -4409,15 +4412,16 @@ class Formula # Whether this {Formula} is deprecated (i.e. warns on installation). # Defaults to false. + # # @see .deprecate! sig { returns(T::Boolean) } def deprecated? @deprecated == true end - # The date that this {Formula} was or becomes deprecated. - # Returns `nil` if no date is specified. + # The date of deprecation of a {Formula}. # + # @return [nil] if no date is specified. # @see .deprecate! sig { returns(T.nilable(Date)) } attr_reader :deprecation_date diff --git a/Library/Homebrew/formula_cellar_checks.rb b/Library/Homebrew/formula_cellar_checks.rb index f2a0ec2985..dbdc055302 100644 --- a/Library/Homebrew/formula_cellar_checks.rb +++ b/Library/Homebrew/formula_cellar_checks.rb @@ -3,7 +3,7 @@ require "utils/shell" -# Checks to perform on a formula's cellar. +# Checks to perform on a formula's keg (versioned Cellar path). module FormulaCellarChecks extend T::Helpers diff --git a/Library/Homebrew/formulary.rb b/Library/Homebrew/formulary.rb index efb2bf65b3..f416dad77c 100644 --- a/Library/Homebrew/formulary.rb +++ b/Library/Homebrew/formulary.rb @@ -80,7 +80,7 @@ module Formulary module PathnameWriteMkpath # TODO: migrate away from refinements here, they don't play nicely with - # Sorbet, when we migrate to `typed: strict` + # Sorbet, when we migrate to `typed: strict` # rubocop:todo Sorbet/BlockMethodDefinition refine Pathname do def write(content, offset = nil, **open_args) @@ -144,7 +144,7 @@ module Formulary end ensure # TODO: Make printing to stdout an error so that we can print a tap name. - # See discussion at https://github.com/Homebrew/brew/pull/20226#discussion_r2195886888 + # See discussion at https://github.com/Homebrew/brew/pull/20226#discussion_r2195886888 if (printed_to_stdout = $stdout.string.strip.presence) opoo <<~WARNING Formula #{name} attempted to print the following while being loaded: @@ -269,7 +269,7 @@ module Formulary end # TODO: migrate away from this inline class here, they don't play nicely with - # Sorbet, when we migrate to `typed: strict` + # Sorbet, when we migrate to `typed: strict` # rubocop:todo Sorbet/BlockMethodDefinition klass = Class.new(::Formula) do @loaded_from_api = true diff --git a/Library/Homebrew/ignorable.rb b/Library/Homebrew/ignorable.rb index 10d7ffe5c3..b1814e7249 100644 --- a/Library/Homebrew/ignorable.rb +++ b/Library/Homebrew/ignorable.rb @@ -20,7 +20,7 @@ module Ignorable def self.hook_raise # TODO: migrate away from this inline class here, they don't play nicely with - # Sorbet, when we migrate to `typed: strict` + # Sorbet, when we migrate to `typed: strict` # rubocop:todo Sorbet/BlockMethodDefinition Object.class_eval do alias_method :original_raise, :raise diff --git a/Library/Homebrew/keg.rb b/Library/Homebrew/keg.rb index 275cc8fed0..34bdcaf389 100644 --- a/Library/Homebrew/keg.rb +++ b/Library/Homebrew/keg.rb @@ -487,7 +487,7 @@ class Keg /^ruby/ :mkpath else - # Everything else is symlinked to the cellar + # Everything else is symlinked to the Cellar :link end end diff --git a/Library/Homebrew/linkage_cache_store.rb b/Library/Homebrew/linkage_cache_store.rb index 2fb45df2e9..18d607b31e 100644 --- a/Library/Homebrew/linkage_cache_store.rb +++ b/Library/Homebrew/linkage_cache_store.rb @@ -55,7 +55,7 @@ class LinkageCacheStore < CacheStore fetch_hash_values(type) end - # Delete the keg from the {LinkageCacheStore} + # Delete the keg from the {LinkageCacheStore}. # # @return [nil] def delete! diff --git a/Library/Homebrew/livecheck/strategy/sourceforge.rb b/Library/Homebrew/livecheck/strategy/sourceforge.rb index eb3effc313..46474a8262 100644 --- a/Library/Homebrew/livecheck/strategy/sourceforge.rb +++ b/Library/Homebrew/livecheck/strategy/sourceforge.rb @@ -25,7 +25,7 @@ module Homebrew # Usually we address this situation by adding a `livecheck` block to # the formula/cask that checks the page for the relevant directory in the # project instead. In this situation, it's necessary to use - # `strategy :page_match` to prevent the {Sourceforge} stratgy from + # `strategy :page_match` to prevent the {Sourceforge} strategy from # being used. # # The default regex matches within `url` attributes in the RSS feed diff --git a/Library/Homebrew/livecheck/strategy/xml.rb b/Library/Homebrew/livecheck/strategy/xml.rb index 5c391be719..93b6f28eeb 100644 --- a/Library/Homebrew/livecheck/strategy/xml.rb +++ b/Library/Homebrew/livecheck/strategy/xml.rb @@ -102,7 +102,7 @@ module Homebrew # Parses XML text and identifies versions using a `strategy` block. # If a regex is provided, it will be passed as the second argument to - # the `strategy` block (after the parsed XML data). + # the `strategy` block (after the parsed XML data). # @param content [String] the XML text to parse and check # @param regex [Regexp, nil] a regex used for matching versions in the # content diff --git a/Library/Homebrew/livecheck/strategy/yaml.rb b/Library/Homebrew/livecheck/strategy/yaml.rb index 41c08ff11b..c39b3e79b0 100644 --- a/Library/Homebrew/livecheck/strategy/yaml.rb +++ b/Library/Homebrew/livecheck/strategy/yaml.rb @@ -63,7 +63,7 @@ module Homebrew # Parses YAML text and identifies versions using a `strategy` block. # If a regex is provided, it will be passed as the second argument to - # the `strategy` block (after the parsed YAML data). + # the `strategy` block (after the parsed YAML data). # @param content [String] the YAML text to parse and check # @param regex [Regexp, nil] a regex used for matching versions in the # content diff --git a/Library/Homebrew/migrator.rb b/Library/Homebrew/migrator.rb index ce3b16fb27..de6fc0732c 100644 --- a/Library/Homebrew/migrator.rb +++ b/Library/Homebrew/migrator.rb @@ -49,7 +49,7 @@ class Migrator # Old name of the formula. attr_reader :oldname - # Path to oldname's cellar. + # Path to oldname's Cellar. attr_reader :old_cellar # Path to oldname pin. @@ -76,10 +76,10 @@ class Migrator # New name of the formula. attr_reader :newname - # Path to newname cellar according to new name. + # Path to newname Cellar according to new name. attr_reader :new_cellar - # True if new cellar existed at initialization time. + # True if new Cellar existed at initialization time. attr_reader :new_cellar_existed # Path to newname pin. diff --git a/Library/Homebrew/os/mac/mach.rb b/Library/Homebrew/os/mac/mach.rb index 9c704de981..44ddf94636 100644 --- a/Library/Homebrew/os/mac/mach.rb +++ b/Library/Homebrew/os/mac/mach.rb @@ -67,7 +67,7 @@ module MachOShim private :mach_data # TODO: See if the `#write!` call can be delayed until - # we know we're not making any changes to the rpaths. + # we know we're not making any changes to the rpaths. def delete_rpath(rpath, **options) candidates = rpaths(resolve_variable_references: false).select do |r| resolve_variable_name(r) == resolve_variable_name(rpath) diff --git a/Library/Homebrew/requirements/macos_requirement.rb b/Library/Homebrew/requirements/macos_requirement.rb index 366348b893..deddc53698 100644 --- a/Library/Homebrew/requirements/macos_requirement.rb +++ b/Library/Homebrew/requirements/macos_requirement.rb @@ -10,7 +10,7 @@ class MacOSRequirement < Requirement attr_reader :comparator, :version # TODO: when Yosemite is removed here, keep these around as empty arrays so we - # can keep the deprecation/disabling code the same. + # can keep the deprecation/disabling code the same. DISABLED_MACOS_VERSIONS = [ :yosemite, ].freeze diff --git a/Library/Homebrew/rubocops/service.rb b/Library/Homebrew/rubocops/service.rb index 32300d97c6..f2429da682 100644 --- a/Library/Homebrew/rubocops/service.rb +++ b/Library/Homebrew/rubocops/service.rb @@ -46,7 +46,7 @@ module RuboCop end end - # This check ensures that cellar paths like `bin` are not referenced + # This check ensures that Cellar paths like `bin` are not referenced # because their `opt_` variants are more portable and work with the API. CELLAR_PATH_AUDIT_CORRECTIONS.each do |path, opt_path| next unless method_calls.key?(path) diff --git a/Library/Homebrew/rubocops/text.rb b/Library/Homebrew/rubocops/text.rb index cc29a70ac6..b6c4f553c2 100644 --- a/Library/Homebrew/rubocops/text.rb +++ b/Library/Homebrew/rubocops/text.rb @@ -171,7 +171,7 @@ module RuboCop end # Check whether value starts with the formula name and then a "/", " " or EOS. - # If we're checking for "#{bin}", we also check for "-" since similar binaries also don't need interpolation. + # If we're checking for "#\\{bin}", we also check for "-" b/c similar binaries don't also need interpolation. sig { params(path: String, starts_with: String, bin: T::Boolean).returns(T::Boolean) } def path_starts_with?(path, starts_with, bin: false) ending = bin ? "/|-|$" : "/| |$" diff --git a/Library/Homebrew/service.rb b/Library/Homebrew/service.rb index b2d974b6aa..e39192990d 100644 --- a/Library/Homebrew/service.rb +++ b/Library/Homebrew/service.rb @@ -539,7 +539,7 @@ module Homebrew @sockets.transform_values { |info| "#{info[:type]}://#{info[:host]}:#{info[:port]}" } .then do |sockets_hash| # TODO: Remove this code when all users are running on versions of Homebrew - # that can process sockets hashes (this commit or later). + # that can process sockets hashes (this commit or later). if sockets_hash.size == 1 && sockets_hash.key?(:listeners) # When original #sockets argument was a string: `sockets "tcp://127.0.0.1:80"` sockets_hash.fetch(:listeners) diff --git a/Library/Homebrew/shims/super/cc b/Library/Homebrew/shims/super/cc index 5fa4876563..1bb5950b39 100755 --- a/Library/Homebrew/shims/super/cc +++ b/Library/Homebrew/shims/super/cc @@ -55,7 +55,7 @@ class Cmd @deps = Set.new(ENV.fetch("HOMEBREW_DEPENDENCIES", "").split(",")) @formula_prefix = ENV["HOMEBREW_FORMULA_PREFIX"] @formula_buildpath = ENV["HOMEBREW_FORMULA_BUILDPATH"] - # matches opt or cellar prefix and formula name + # matches opt or Cellar prefix and formula name @keg_regex = %r{(#{Regexp.escape(opt)}|#{Regexp.escape(cellar)})/([\w+-.@]+)} end diff --git a/Library/Homebrew/tap.rb b/Library/Homebrew/tap.rb index 1cf3b3f36c..4d5d2df15e 100644 --- a/Library/Homebrew/tap.rb +++ b/Library/Homebrew/tap.rb @@ -5,7 +5,7 @@ require "api" require "commands" require "settings" -# A {Tap} is used to extend the formulae provided by Homebrew core. +# A {Tap} is used to encapsulate Homebrew formulae, casks and custom commands. # Usually, it's synced with a remote Git repository. And it's likely # a GitHub repository with the name of `user/homebrew-repository`. In such # cases, `user/repository` will be used as the {#name} of this {Tap}, where diff --git a/Library/Homebrew/test/dev-cmd/bottle_spec.rb b/Library/Homebrew/test/dev-cmd/bottle_spec.rb index 2faf9b36ab..5b76df2bc2 100644 --- a/Library/Homebrew/test/dev-cmd/bottle_spec.rb +++ b/Library/Homebrew/test/dev-cmd/bottle_spec.rb @@ -414,8 +414,8 @@ RSpec.describe Homebrew::DevCmd::Bottle do end # TODO: add deduplication tests e.g. - # it "deduplicates JSON files with matching macOS checksums" - # it "deduplicates JSON files with matching OS checksums" do + # it "deduplicates JSON files with matching macOS checksums" + # it "deduplicates JSON files with matching OS checksums" do end describe "#merge_bottle_spec" do diff --git a/Library/Homebrew/test/dev-cmd/irb_spec.rb b/Library/Homebrew/test/dev-cmd/irb_spec.rb index 4ba95bc123..dbde40a3d0 100644 --- a/Library/Homebrew/test/dev-cmd/irb_spec.rb +++ b/Library/Homebrew/test/dev-cmd/irb_spec.rb @@ -29,8 +29,8 @@ RSpec.describe Homebrew::DevCmd::Irb do .and be_a_success # TODO: newer Ruby only supports history saving in interactive sessions - # and not if you feed in data from a file or stdin like we are doing here. - # The test will need to be adjusted for this to work. + # and not if you feed in data from a file or stdin like we are doing here. + # The test will need to be adjusted for this to work. # expect(history_file).to exist end end diff --git a/Library/Homebrew/test/utils/curl_spec.rb b/Library/Homebrew/test/utils/curl_spec.rb index 8296e1d0c3..5b04c09722 100644 --- a/Library/Homebrew/test/utils/curl_spec.rb +++ b/Library/Homebrew/test/utils/curl_spec.rb @@ -90,7 +90,7 @@ RSpec.describe "Utils::Curl" do details[:cloudflare][:wrong_server][:headers]["server"] = "nginx 1.2.3" # TODO: Make the Incapsula test data more realistic once we can find an - # example website to reference. + # example website to reference. details[:incapsula][:single_cookie_visid_incap] = details[:normal][:no_cookie].deep_dup details[:incapsula][:single_cookie_visid_incap][:headers]["set-cookie"] = "visid_incap_something=something" diff --git a/Library/Homebrew/uninstall.rb b/Library/Homebrew/uninstall.rb index 6acafea7eb..ce19765f81 100644 --- a/Library/Homebrew/uninstall.rb +++ b/Library/Homebrew/uninstall.rb @@ -71,7 +71,7 @@ module Homebrew excluded_names = Homebrew::API::Formula.all_formulae.keys maybe_paths = maybe_paths.reject do |path| # Remove extension only if a file - # (f.e. directory with name "openssl@1.1" will be trimmed to "openssl@1") + # (e.g. directory with name "openssl@1.1" will be trimmed to "openssl@1") basename = if File.directory?(path) File.basename(path) else diff --git a/Library/Homebrew/yard/docstring_parser.rb b/Library/Homebrew/yard/docstring_parser.rb index 67bebedbee..b36262a254 100644 --- a/Library/Homebrew/yard/docstring_parser.rb +++ b/Library/Homebrew/yard/docstring_parser.rb @@ -6,14 +6,17 @@ module Homebrew module YARD class DocstringParser < ::YARD::DocstringParser # Every `Object` has these methods. - OVERRIDABLE_METHODS = [ - :hash, :inspect, :to_s, - :<=>, :===, :!~, :eql?, :equal?, :!, :==, :!= - ].freeze - private_constant :OVERRIDABLE_METHODS - - SELF_EXPLANATORY_METHODS = [:to_yaml, :to_json, :to_str].freeze - private_constant :SELF_EXPLANATORY_METHODS + unless const_defined?(:OVERRIDABLE_METHODS, false) + OVERRIDABLE_METHODS = [ + :hash, :inspect, :to_s, + :<=>, :===, :!~, :eql?, :equal?, :!, :==, :!= + ].freeze + private_constant :OVERRIDABLE_METHODS + end + unless const_defined?(:SELF_EXPLANATORY_METHODS, false) + SELF_EXPLANATORY_METHODS = [:to_yaml, :to_json, :to_str].freeze + private_constant :SELF_EXPLANATORY_METHODS + end def parse_content(content) # Convert plain text to tags.