diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 09af8ebef8..ff2c5e3577 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1 +1 @@ -# Please fill out one of the templates on: https://github.com/Homebrew/brew/issues/new/choose or we will close it without comment. +Please fill out one of the templates on https://github.com/Homebrew/brew/issues/new/choose or we will close your issue without comment. diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 30e4f549ce..1a62b3a1cb 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -25,9 +25,22 @@ jobs: - name: Install vale run: brew install vale - - name: Run vale for docs linting - working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs - run: vale . + - name: Lint docs + working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }} + run: | + set -euo pipefail + + # Avoid failing on broken symlinks. + rm Library/Homebrew/os/mac/pkgconfig/fuse/fuse.pc + rm Library/Homebrew/os/mac/pkgconfig/fuse/osxfuse.pc + + # No ignore support (https://github.com/errata-ai/vale/issues/131). + rm -r Library/Homebrew/vendor + + vale . + + # Restore removed files. + git reset --hard - name: Install Ruby uses: ruby/setup-ruby@1198b074305f9356bd56dd4b311757cc0dab2f1c # v1.175.1 diff --git a/.gitignore b/.gitignore index 55a5659a84..d34dee6a00 100644 --- a/.gitignore +++ b/.gitignore @@ -107,6 +107,7 @@ **/vendor/bundle/ruby/*/gems/rainbow-*/ **/vendor/bundle/ruby/*/gems/rbi-*/ **/vendor/bundle/ruby/*/gems/rdoc-*/ +**/vendor/bundle/ruby/*/gems/redcarpet-*/ **/vendor/bundle/ruby/*/gems/regexp_parser-*/ **/vendor/bundle/ruby/*/gems/rexml-*/ **/vendor/bundle/ruby/*/gems/rspec-*/ diff --git a/.vale.ini b/.vale.ini index 8aeb075101..13f035651a 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,4 +1,7 @@ StylesPath = ./docs/vale-styles -[*.md] +[formats] +rb = md + +[*.{md,rb}] BasedOnStyles = Homebrew diff --git a/Library/Homebrew/.rubocop.yml b/Library/Homebrew/.rubocop.yml index 3c6e03b77a..a35001a936 100644 --- a/Library/Homebrew/.rubocop.yml +++ b/Library/Homebrew/.rubocop.yml @@ -70,6 +70,11 @@ Style/Documentation: - version.rb - tap.rb +Homebrew/NegateInclude: + Exclude: + # YARD runs stand-alone. + - yard/docstring_parser.rb + Style/DocumentationMethod: Include: - "formula.rb" diff --git a/Library/Homebrew/Gemfile b/Library/Homebrew/Gemfile index d8c898284f..1933a098e4 100644 --- a/Library/Homebrew/Gemfile +++ b/Library/Homebrew/Gemfile @@ -16,6 +16,7 @@ end # installed gems (should all be require: false) # ALL gems that are not vendored should be in a group group :doc, optional: true do + gem "redcarpet", require: false gem "yard", require: false gem "yard-sorbet", require: false end diff --git a/Library/Homebrew/Gemfile.lock b/Library/Homebrew/Gemfile.lock index 3102788ac6..80af1b6fd3 100644 --- a/Library/Homebrew/Gemfile.lock +++ b/Library/Homebrew/Gemfile.lock @@ -53,6 +53,7 @@ GEM rbi (0.1.12) prism (>= 0.18.0, < 0.28) sorbet-runtime (>= 0.5.9204) + redcarpet (3.6.0) regexp_parser (2.9.0) rexml (3.2.6) rspec (3.13.0) @@ -175,6 +176,7 @@ DEPENDENCIES patchelf plist pry + redcarpet rexml rspec rspec-github diff --git a/Library/Homebrew/PATH.rb b/Library/Homebrew/PATH.rb index 474bd2f0c1..577bdc8ab9 100644 --- a/Library/Homebrew/PATH.rb +++ b/Library/Homebrew/PATH.rb @@ -60,7 +60,6 @@ class PATH @paths.join(File::PATH_SEPARATOR) end - # @!visibility private sig { returns(String) } def to_s = to_str diff --git a/Library/Homebrew/abstract_command.rb b/Library/Homebrew/abstract_command.rb index 9d11837cc1..e24c7ae719 100644 --- a/Library/Homebrew/abstract_command.rb +++ b/Library/Homebrew/abstract_command.rb @@ -6,9 +6,10 @@ require "cli/parser" module Homebrew # Subclass this to implement a `brew` command. This is preferred to declaring a named function in the `Homebrew` # module, because: + # # - Each Command lives in an isolated namespace. # - Each Command implements a defined interface. - # - `args` is available as an ivar, and thus does not need to be passed as an argument to helper methods. + # - `args` is available as an instance method and thus does not need to be passed as an argument to helper methods. # - Subclasses no longer need to reference `CLI::Parser` or parse args explicitly. # # To subclass, implement a `run` method and provide a `cmd_args` block to document the command and its allowed args. diff --git a/Library/Homebrew/attestation.rb b/Library/Homebrew/attestation.rb index 2dc57ad57a..9f40bf1fe9 100644 --- a/Library/Homebrew/attestation.rb +++ b/Library/Homebrew/attestation.rb @@ -39,8 +39,8 @@ module Homebrew sig { returns(Pathname) } def self.gh_executable # NOTE: We disable HOMEBREW_VERIFY_ATTESTATIONS when installing `gh` itself, - # to prevent a cycle during bootstrapping. This can eventually be resolved - # by vendoring a pure-Ruby Sigstore verifier client. + # to prevent a cycle during bootstrapping. This can eventually be resolved + # by vendoring a pure-Ruby Sigstore verifier client. @gh_executable ||= T.let(with_env("HOMEBREW_VERIFY_ATTESTATIONS" => nil) do ensure_executable!("gh") end, T.nilable(Pathname)) diff --git a/Library/Homebrew/brew.sh b/Library/Homebrew/brew.sh index 3ff4e3e928..e2303765d3 100644 --- a/Library/Homebrew/brew.sh +++ b/Library/Homebrew/brew.sh @@ -265,7 +265,7 @@ EOS fi } -# NOTE: the members of the array in the second arg must not have spaces! +# NOTE: The members of the array in the second arg must not have spaces! check-array-membership() { local item=$1 shift diff --git a/Library/Homebrew/brew_irbrc b/Library/Homebrew/brew_irbrc index b31faa3525..00217d3fdd 100644 --- a/Library/Homebrew/brew_irbrc +++ b/Library/Homebrew/brew_irbrc @@ -1,6 +1,6 @@ -# Note: that we use a non-standard config file name to reduce -# name clashes with other IRB config files like `.irbrc`. -# Note #2: This doesn't work with system Ruby for some reason. +# NOTE: We use a non-standard config file name to reduce name clashes with +# other IRB config files like `.irbrc`. +# NOTE: This doesn't work with system Ruby for some reason. require 'irb/completion' diff --git a/Library/Homebrew/build_environment.rb b/Library/Homebrew/build_environment.rb index a07db8e88b..d2028f2c62 100644 --- a/Library/Homebrew/build_environment.rb +++ b/Library/Homebrew/build_environment.rb @@ -28,7 +28,7 @@ class BuildEnvironment # DSL for specifying build environment settings. module DSL # Initialise @env for each class which may use this DSL (e.g. each formula subclass). - # `env` may never be called, and it needs to be initialised before the class is frozen. + # `env` may never be called and it needs to be initialised before the class is frozen. def inherited(child) super child.instance_eval do diff --git a/Library/Homebrew/build_options.rb b/Library/Homebrew/build_options.rb index 75f39c3193..ccc3117386 100644 --- a/Library/Homebrew/build_options.rb +++ b/Library/Homebrew/build_options.rb @@ -9,16 +9,26 @@ class BuildOptions end # True if a {Formula} is being built with a specific option. - # 
args << "--i-want-spam" if build.with? "spam"
   #
+  # ### Examples
+  #
+  # ```ruby
+  # args << "--i-want-spam" if build.with? "spam"
+  # ```
+  #
+  # ```ruby
   # args << "--qt-gui" if build.with? "qt" # "--with-qt" ==> build.with? "qt"
+  # ```
   #
-  # # If a formula presents a user with a choice, but the choice must be fulfilled:
+  # If a formula presents a user with a choice, but the choice must be fulfilled:
+  #
+  # ```ruby
   # if build.with? "example2"
   #   args << "--with-example2"
   # else
   #   args << "--with-example1"
-  # end
+ # end + # ``` def with?(val) option_names = val.respond_to?(:option_names) ? val.option_names : [val] @@ -34,7 +44,12 @@ class BuildOptions end # True if a {Formula} is being built without a specific option. - # 
args << "--no-spam-plz" if build.without? "spam"
+ # + # ### Example + # + # ```ruby + # args << "--no-spam-plz" if build.without? "spam" + # ``` def without?(val) !with?(val) end @@ -45,19 +60,33 @@ class BuildOptions end # True if a {Formula} is being built with {Formula.head} instead of {Formula.stable}. - # 
args << "--some-new-stuff" if build.head?
- # 
# If there are multiple conditional arguments use a block instead of lines.
+  #
+  # ### Examples
+  #
+  # ```ruby
+  # args << "--some-new-stuff" if build.head?
+  # ```
+  #
+  # If there are multiple conditional arguments use a block instead of lines.
+  #
+  # ```ruby
   # if build.head?
   #   args << "--i-want-pizza"
   #   args << "--and-a-cold-beer" if build.with? "cold-beer"
-  # end
+ # end + # ``` def head? include? "HEAD" end # True if a {Formula} is being built with {Formula.stable} instead of {Formula.head}. # This is the default. - # 
args << "--some-beta" if build.head?
+ # + # ### Example + # + # ```ruby + # args << "--some-beta" if build.head? + # ``` def stable? !head? end diff --git a/Library/Homebrew/cask/artifact/abstract_artifact.rb b/Library/Homebrew/cask/artifact/abstract_artifact.rb index a202cad6b4..e722d0bc0f 100644 --- a/Library/Homebrew/cask/artifact/abstract_artifact.rb +++ b/Library/Homebrew/cask/artifact/abstract_artifact.rb @@ -147,7 +147,6 @@ module Cask cask.config end - # @!visibility private sig { returns(String) } def to_s "#{summarize} (#{self.class.english_name})" diff --git a/Library/Homebrew/cask/audit.rb b/Library/Homebrew/cask/audit.rb index 067e775c9c..bb3de17d02 100644 --- a/Library/Homebrew/cask/audit.rb +++ b/Library/Homebrew/cask/audit.rb @@ -685,7 +685,7 @@ module Cask sig { void } def audit_github_repository_archived - # Deprecated/disabled casks may have an archived repo. + # Deprecated/disabled casks may have an archived repository. return if cask.discontinued? || cask.deprecated? || cask.disabled? user, repo = get_repo_data(%r{https?://github\.com/([^/]+)/([^/]+)/?.*}) if online? @@ -699,7 +699,7 @@ module Cask sig { void } def audit_gitlab_repository_archived - # Deprecated/disabled casks may have an archived repo. + # Deprecated/disabled casks may have an archived repository. return if cask.discontinued? || cask.deprecated? || cask.disabled? user, repo = get_repo_data(%r{https?://gitlab\.com/([^/]+)/([^/]+)/?.*}) if online? diff --git a/Library/Homebrew/cask/cask.rb b/Library/Homebrew/cask/cask.rb index e7856806ce..5ffd9fb797 100644 --- a/Library/Homebrew/cask/cask.rb +++ b/Library/Homebrew/cask/cask.rb @@ -78,7 +78,8 @@ module Cask @allow_reassignment = allow_reassignment @loaded_from_api = loaded_from_api @loader = loader - # Sorbet has trouble with bound procs assigned to ivars: https://github.com/sorbet/sorbet/issues/6843 + # Sorbet has trouble with bound procs assigned to instance variables: + # https://github.com/sorbet/sorbet/issues/6843 instance_variable_set(:@block, block) @default_config = config || Config.new @@ -323,11 +324,9 @@ module Cask end # @api public - # @!visibility private sig { returns(String) } def to_s = token - # @!visibility private sig { returns(String) } def inspect "#" diff --git a/Library/Homebrew/cask/dsl.rb b/Library/Homebrew/cask/dsl.rb index 24424f3f70..62dee57438 100644 --- a/Library/Homebrew/cask/dsl.rb +++ b/Library/Homebrew/cask/dsl.rb @@ -112,6 +112,16 @@ module Cask @token = cask.token end + # Specifies the cask's name. + # + # NOTE: Multiple names can be specified. + # + # ### Example + # + # ```ruby + # name "Visual Studio Code" + # ``` + # # @api public def name(*args) @name ||= [] @@ -120,6 +130,14 @@ module Cask @name.concat(args.flatten) end + # Describes the cask. + # + # ### Example + # + # ```ruby + # desc "Open-source code editor" + # ``` + # # @api public def desc(description = nil) set_unique_stanza(:desc, description.nil?) { description } @@ -146,6 +164,14 @@ module Cask raise CaskInvalidError.new(cask, "'#{stanza}' stanza failed with: #{e}") end + # Sets the cask's homepage. + # + # ### Example + # + # ```ruby + # homepage "https://code.visualstudio.com/" + # ``` + # # @api public def homepage(homepage = nil) set_unique_stanza(:homepage, homepage.nil?) { homepage } @@ -201,6 +227,14 @@ module Cask @language_blocks.keys.flatten end + # Sets the cask's download URL. + # + # ### Example + # + # ```ruby + # url "https://update.code.visualstudio.com/#{version}/#{arch}/stable" + # ``` + # # @api public def url(*args, **options, &block) caller_location = T.must(caller_locations).fetch(0) @@ -214,6 +248,8 @@ module Cask end end + # Sets the cask's appcast URL. + # # @api public def appcast(*args, **kwargs) set_unique_stanza(:appcast, args.empty? && kwargs.empty?) do @@ -222,6 +258,22 @@ module Cask end end + # Sets the cask's container type or nested container path. + # + # ### Examples + # + # The container is a nested disk image: + # + # ```ruby + # container nested: "orca-#{version}.dmg" + # ``` + # + # The container should not be unarchived: + # + # ```ruby + # container type: :naked + # ``` + # # @api public def container(**kwargs) set_unique_stanza(:container, kwargs.empty?) do @@ -229,6 +281,15 @@ module Cask end end + # Sets the cask's version. + # + # ### Example + # + # ```ruby + # version "1.88.1" + # ``` + # + # @see DSL::Version # @api public def version(arg = nil) set_unique_stanza(:version, arg.nil?) do @@ -240,6 +301,23 @@ module Cask end end + # Sets the cask's download checksum. + # + # ### Example + # + # For universal or single-architecture downloads: + # + # ```ruby + # sha256 "7bdb497080ffafdfd8cc94d8c62b004af1be9599e865e5555e456e2681e150ca" + # ``` + # + # For architecture-dependent downloads: + # + # ```ruby + # sha256 arm: "7bdb497080ffafdfd8cc94d8c62b004af1be9599e865e5555e456e2681e150ca", + # intel: "b3c1c2442480a0219b9e05cf91d03385858c20f04b764ec08a3fa83d1b27e7b2" + # ``` + # # @api public def sha256(arg = nil, arm: nil, intel: nil) should_return = arg.nil? && arm.nil? && intel.nil? @@ -259,6 +337,14 @@ module Cask end end + # Sets the cask's architecture strings. + # + # ### Example + # + # ```ruby + # arch arm: "darwin-arm64", intel: "darwin" + # ``` + # # @api public def arch(arm: nil, intel: nil) should_return = arm.nil? && intel.nil? @@ -270,7 +356,10 @@ module Cask end end - # `depends_on` uses a load method so that multiple stanzas can be merged. + # Declare dependencies and requirements for a cask. + # + # NOTE: Multiple dependencies can be specified. + # # @api public def depends_on(**kwargs) @depends_on ||= DSL::DependsOn.new @@ -284,9 +373,11 @@ module Cask @depends_on end + # Declare conflicts that keep a cask from installing or working correctly. + # # @api public def conflicts_with(**kwargs) - # TODO: remove this constraint, and instead merge multiple conflicts_with stanzas + # TODO: Remove this constraint and instead merge multiple `conflicts_with` stanzas set_unique_stanza(:conflicts_with, kwargs.empty?) { DSL::ConflictsWith.new(**kwargs) } end @@ -298,6 +389,8 @@ module Cask cask.caskroom_path end + # The staged location for this cask, including version number. + # # @api public def staged_path return @staged_path if @staged_path @@ -306,6 +399,8 @@ module Cask @staged_path = caskroom_path.join(cask_version.to_s) end + # Provide the user with cask-specific information at install time. + # # @api public def caveats(*strings, &block) @caveats ||= DSL::Caveats.new(cask) @@ -326,11 +421,15 @@ module Cask @caveats&.discontinued? == true end + # Asserts that the cask artifacts auto-update. + # # @api public def auto_updates(auto_updates = nil) set_unique_stanza(:auto_updates, auto_updates.nil?) { auto_updates } end + # Automatically fetch the latest version of a cask from changelogs. + # # @api public def livecheck(&block) @livecheck ||= Livecheck.new(cask) @@ -344,6 +443,10 @@ module Cask @livecheck.instance_eval(&block) end + # Declare that a cask is no longer functional or supported. + # + # NOTE: A warning will be shown when trying to install this cask. + # # @api public def deprecate!(date:, because:) @deprecation_date = Date.parse(date) @@ -353,6 +456,10 @@ module Cask @deprecated = true end + # Declare that a cask is no longer functional or supported. + # + # NOTE: An error will be thrown when trying to install this cask. + # # @api public def disable!(date:, because:) @disable_date = Date.parse(date) @@ -405,6 +512,8 @@ module Cask true end + # The directory `app`s are installed into. + # # @api public def appdir return HOMEBREW_CASK_APPDIR_PLACEHOLDER if Cask.generating_hash? diff --git a/Library/Homebrew/cask/dsl/caveats.rb b/Library/Homebrew/cask/dsl/caveats.rb index 2ccb4396be..53b029e75e 100644 --- a/Library/Homebrew/cask/dsl/caveats.rb +++ b/Library/Homebrew/cask/dsl/caveats.rb @@ -37,7 +37,6 @@ module Cask private_class_method :caveat - # @!visibility private sig { returns(String) } def to_s (@custom_caveats + @built_in_caveats.values).join("\n") diff --git a/Library/Homebrew/cask/dsl/container.rb b/Library/Homebrew/cask/dsl/container.rb index bb4beaa27f..54bc3bc4e8 100644 --- a/Library/Homebrew/cask/dsl/container.rb +++ b/Library/Homebrew/cask/dsl/container.rb @@ -27,7 +27,6 @@ module Cask pairs.to_yaml end - # @!visibility private sig { returns(String) } def to_s = pairs.inspect end diff --git a/Library/Homebrew/cask/dsl/postflight.rb b/Library/Homebrew/cask/dsl/postflight.rb index 3ceabd9cab..0747ff8def 100644 --- a/Library/Homebrew/cask/dsl/postflight.rb +++ b/Library/Homebrew/cask/dsl/postflight.rb @@ -9,8 +9,8 @@ module Cask class Postflight < Base include Staged - def suppress_move_to_applications(_options = {}) - odisabled "Cask::DSL#suppress_move_to_applications" + def suppress_move_to_applications(**_options) + odisabled "`Cask::DSL::Postflight#suppress_move_to_applications`" end end end diff --git a/Library/Homebrew/cask/dsl/version.rb b/Library/Homebrew/cask/dsl/version.rb index 853a4f191c..30f8ebcd64 100644 --- a/Library/Homebrew/cask/dsl/version.rb +++ b/Library/Homebrew/cask/dsl/version.rb @@ -94,70 +94,94 @@ module Cask to_s == "latest" end + # The major version. + # # @api public sig { returns(T.self_type) } def major version { slice(MAJOR_MINOR_PATCH_REGEX, 1) } end + # The minor version. + # # @api public sig { returns(T.self_type) } def minor version { slice(MAJOR_MINOR_PATCH_REGEX, 2) } end + # The patch version. + # # @api public sig { returns(T.self_type) } def patch version { slice(MAJOR_MINOR_PATCH_REGEX, 3) } end + # The major and minor version. + # # @api public sig { returns(T.self_type) } def major_minor version { [major, minor].reject(&:empty?).join(".") } end + # The major, minor and patch version. + # # @api public sig { returns(T.self_type) } def major_minor_patch version { [major, minor, patch].reject(&:empty?).join(".") } end + # The minor and patch version. + # # @api public sig { returns(T.self_type) } def minor_patch version { [minor, patch].reject(&:empty?).join(".") } end + # The comma separated values of the version as array. + # # @api public sig { returns(T::Array[Version]) } # Only top-level T.self_type is supported https://sorbet.org/docs/self-type def csv split(",").map { self.class.new(_1) } end + # The version part before the first comma. + # # @api public sig { returns(T.self_type) } def before_comma version { split(",", 2).first } end + # The version part after the first comma. + # # @api public sig { returns(T.self_type) } def after_comma version { split(",", 2).second } end + # The version without any dividers. + # + # @see DIVIDER_REGEX # @api public sig { returns(T.self_type) } def no_dividers version { gsub(DIVIDER_REGEX, "") } end + # The version with the given record separator removed from the end. + # + # @see String#chomp # @api public - sig { params(separator: T.nilable(String)).returns(T.self_type) } - def chomp(separator = nil) - version { to_s.chomp(T.unsafe(separator)) } + sig { params(separator: String).returns(T.self_type) } + def chomp(separator = T.unsafe(nil)) + version { to_s.chomp(separator) } end private diff --git a/Library/Homebrew/cask/exceptions.rb b/Library/Homebrew/cask/exceptions.rb index fc354f4e19..aa4e91863d 100644 --- a/Library/Homebrew/cask/exceptions.rb +++ b/Library/Homebrew/cask/exceptions.rb @@ -13,7 +13,6 @@ module Cask @errors = errors end - # @!visibility private sig { returns(String) } def to_s <<~EOS @@ -41,7 +40,6 @@ module Cask # Error when a cask is not installed. class CaskNotInstalledError < AbstractCaskErrorWithToken - # @!visibility private sig { returns(String) } def to_s "Cask '#{token}' is not installed." @@ -57,7 +55,6 @@ module Cask @message = message end - # @!visibility private sig { returns(String) } def to_s "Cask '#{token}' has been #{message}" @@ -73,7 +70,6 @@ module Cask @conflicting_cask = conflicting_cask end - # @!visibility private sig { returns(String) } def to_s "Cask '#{token}' conflicts with '#{conflicting_cask}'." @@ -82,7 +78,6 @@ module Cask # Error when a cask is not available. class CaskUnavailableError < AbstractCaskErrorWithToken - # @!visibility private sig { returns(String) } def to_s "Cask '#{token}' is unavailable#{reason.empty? ? "." : ": #{reason}"}" @@ -91,7 +86,6 @@ module Cask # Error when a cask is unreadable. class CaskUnreadableError < CaskUnavailableError - # @!visibility private sig { returns(String) } def to_s "Cask '#{token}' is unreadable#{reason.empty? ? "." : ": #{reason}"}" @@ -107,7 +101,6 @@ module Cask @tap = tap end - # @!visibility private sig { returns(String) } def to_s s = super @@ -142,7 +135,6 @@ module Cask # Error when a cask already exists. class CaskAlreadyCreatedError < AbstractCaskErrorWithToken - # @!visibility private sig { returns(String) } def to_s %Q(Cask '#{token}' already exists. Run #{Formatter.identifier("brew edit --cask #{token}")} to edit it.) @@ -151,7 +143,6 @@ module Cask # Error when there is a cyclic cask dependency. class CaskCyclicDependencyError < AbstractCaskErrorWithToken - # @!visibility private sig { returns(String) } def to_s "Cask '#{token}' includes cyclic dependencies on other Casks#{reason.empty? ? "." : ": #{reason}"}" @@ -160,7 +151,6 @@ module Cask # Error when a cask depends on itself. class CaskSelfReferencingDependencyError < CaskCyclicDependencyError - # @!visibility private sig { returns(String) } def to_s "Cask '#{token}' depends on itself." @@ -169,7 +159,6 @@ module Cask # Error when no cask is specified. class CaskUnspecifiedError < CaskError - # @!visibility private sig { returns(String) } def to_s "This command requires a Cask token." @@ -178,7 +167,6 @@ module Cask # Error when a cask is invalid. class CaskInvalidError < AbstractCaskErrorWithToken - # @!visibility private sig { returns(String) } def to_s "Cask '#{token}' definition is invalid#{reason.empty? ? "." : ": #{reason}"}" @@ -203,7 +191,6 @@ module Cask @reason = reason end - # @!visibility private sig { returns(String) } def to_s s = +"Failed to quarantine #{path}." @@ -220,7 +207,6 @@ module Cask # Error while propagating quarantine information to subdirectories. class CaskQuarantinePropagationError < CaskQuarantineError - # @!visibility private sig { returns(String) } def to_s s = +"Failed to quarantine one or more files within #{path}." @@ -237,7 +223,6 @@ module Cask # Error while removing quarantine information. class CaskQuarantineReleaseError < CaskQuarantineError - # @!visibility private sig { returns(String) } def to_s s = +"Failed to release #{path} from quarantine." diff --git a/Library/Homebrew/cask/url.rb b/Library/Homebrew/cask/url.rb index 4afd746397..ca79267196 100644 --- a/Library/Homebrew/cask/url.rb +++ b/Library/Homebrew/cask/url.rb @@ -17,22 +17,32 @@ module Cask extend Forwardable def_delegators :uri, :path, :scheme, :to_s - # @api public sig { params( uri: T.any(URI::Generic, String), + # @api public verified: T.nilable(String), + # @api public using: T.any(Class, Symbol, NilClass), + # @api public tag: T.nilable(String), + # @api public branch: T.nilable(String), + # @api public revisions: T.nilable(T::Array[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 } @@ -77,8 +87,19 @@ module Cask end class BlockDSL - # To access URL associated with page contents. + # Allow accessing the URL associated with page contents. module PageWithURL + # Get the URL of the fetched page. + # + # ### Example + # + # ```ruby + # url "https://example.org/download" do |page| + # file = page[/href="([^"]+.dmg)"/, 1] + # URL.join(page.url, file) + # end + # ``` + # # @api public sig { returns(URI::Generic) } attr_accessor :url @@ -87,12 +108,12 @@ module Cask sig { params( uri: T.nilable(T.any(URI::Generic, String)), - dsl: T.nilable(::Cask::DSL), + dsl: ::Cask::DSL, block: T.proc.params(arg0: T.all(String, PageWithURL)) .returns(T.any(T.any(URI::Generic, String), [T.any(URI::Generic, String), Hash])), ).void } - def initialize(uri, dsl: nil, &block) + def initialize(uri, dsl:, &block) @uri = uri @dsl = dsl @block = block @@ -114,6 +135,8 @@ module Cask end end + # Allows calling a nested `url` stanza in a `url do` block. + # # @api public sig { params( @@ -123,10 +146,12 @@ module Cask ).returns(T.any(T.any(URI::Generic, String), [T.any(URI::Generic, String), Hash])) } def url(uri, &block) - self.class.new(uri, &block).call + self.class.new(uri, dsl: @dsl, &block).call end private :url + # This allows calling DSL methods from inside a `url` block. + # # @api public def method_missing(method, *args, &block) if @dsl.respond_to?(method) @@ -135,10 +160,12 @@ module Cask super end end + private :method_missing def respond_to_missing?(method, include_all) @dsl.respond_to?(method, include_all) || super end + private :respond_to_missing? end sig { @@ -187,7 +214,7 @@ module Cask super( if block LazyObject.new do - uri2, options = *BlockDSL.new(uri, dsl:, &block).call + uri2, options = *BlockDSL.new(uri, dsl: T.must(dsl), &block).call options ||= {} DSL.new(uri2, **options) end diff --git a/Library/Homebrew/cask/utils.rb b/Library/Homebrew/cask/utils.rb index 8a8cddfbcc..2fe99ae3fa 100644 --- a/Library/Homebrew/cask/utils.rb +++ b/Library/Homebrew/cask/utils.rb @@ -68,9 +68,9 @@ module Cask unless tried_permissions print_stderr = Context.current.debug? || Context.current.verbose? # TODO: Better handling for the case where path is a symlink. - # The -h and -R flags cannot be combined, and behavior is + # The `-h` and `-R` flags cannot be combined and behavior is # dependent on whether the file argument has a trailing - # slash. This should do the right thing, but is fragile. + # slash. This should do the right thing, but is fragile. command.run("/usr/bin/chflags", print_stderr:, args: command_args + ["--", "000", path]) @@ -87,7 +87,7 @@ module Cask unless tried_ownership # in case of ownership problems # TODO: Further examine files to see if ownership is the problem - # before using sudo+chown + # before using `sudo` and `chown`. ohai "Using sudo to gain ownership of path '#{path}'" command.run("/usr/sbin/chown", args: command_args + ["--", User.current, path], diff --git a/Library/Homebrew/cleaner.rb b/Library/Homebrew/cleaner.rb index 5f9217aeb3..79f2734f18 100644 --- a/Library/Homebrew/cleaner.rb +++ b/Library/Homebrew/cleaner.rb @@ -25,27 +25,28 @@ class Cleaner def clean ObserverPathnameExtension.reset_counts! - # Many formulae include 'lib/charset.alias', but it is not strictly needed - # and will conflict if more than one formula provides it + # Many formulae include `lib/charset.alias`, but it is not strictly needed + # and will conflict if more than one formula provides it. observe_file_removal @formula.lib/"charset.alias" [@formula.bin, @formula.sbin, @formula.lib].each { |dir| clean_dir(dir) if dir.exist? } - # Get rid of any info 'dir' files, so they don't conflict at the link stage + # Get rid of any info `dir` files, so they don't conflict at the link stage. # - # The 'dir' files come in at least 3 locations: + # The `dir` files come in at least 3 locations: # - # 1. 'info/dir' - # 2. 'info/#{name}/dir' - # 3. 'info/#{arch}/dir' + # 1. `info/dir` + # 2. `info/#{name}/dir` + # 3. `info/#{arch}/dir` # - # Of these 3 only 'info/#{name}/dir' is safe to keep since the rest will + # Of these 3 only `info/#{name}/dir` is safe to keep since the rest will # conflict with other formulae because they use a shared location. # - # See [cleaner: recursively delete info `dir`s by gromgit · Pull Request - # #11597][1], [emacs 28.1 bottle does not contain `dir` file · Issue - # #100190][2], and [Keep `info/#{f.name}/dir` files in cleaner by - # timvisher][3] for more info. + # See + # [cleaner: recursively delete info `dir`s][1], + # [emacs 28.1 bottle does not contain `dir` file][2] and + # [Keep `info/#{f.name}/dir` files in cleaner][3] + # for more info. # # [1]: https://github.com/Homebrew/brew/pull/11597 # [2]: https://github.com/Homebrew/homebrew-core/issues/100190 @@ -114,15 +115,15 @@ class Cleaner # created as part of installing any Perl module. PERL_BASENAMES = Set.new(%w[perllocal.pod .packlist]).freeze - # Clean a top-level (bin, sbin, lib) directory, recursively, by fixing file + # Clean a top-level (`bin`, `sbin`, `lib`) directory, recursively, by fixing file # permissions and removing .la files, unless the files (or parent # directories) are protected by skip_clean. # - # bin and sbin should not have any subdirectories; if either do that is - # caught as an audit warning + # `bin` and `sbin` should not have any subdirectories; if either do that is + # caught as an audit warning. # - # lib may have a large directory tree (see Erlang for instance), and - # clean_dir applies cleaning rules to the entire tree + # `lib` may have a large directory tree (see Erlang for instance) and + # clean_dir applies cleaning rules to the entire tree. sig { params(directory: Pathname).void } def clean_dir(directory) directory.find do |path| @@ -137,7 +138,7 @@ class Cleaner elsif path.symlink? # Skip it. else - # Set permissions for executables and non-executables + # Set permissions for executables and non-executables. perms = if executable_path?(path) 0555 else diff --git a/Library/Homebrew/cleanup.rb b/Library/Homebrew/cleanup.rb index ae44d69f9a..fd0c2d30de 100644 --- a/Library/Homebrew/cleanup.rb +++ b/Library/Homebrew/cleanup.rb @@ -376,7 +376,7 @@ module Homebrew def cache_files files = cache.directory? ? cache.children : [] cask_files = (cache/"Cask").directory? ? (cache/"Cask").children : [] - api_source_files = (cache/"api-source").glob("*/*/*/*/*") # org/repo/git_head/type/file.rb + api_source_files = (cache/"api-source").glob("*/*/*/*/*") # `////.rb` gh_actions_artifacts = (cache/"gh-actions-artifact").directory? ? (cache/"gh-actions-artifact").children : [] files.map { |path| { path:, type: nil } } + @@ -571,8 +571,8 @@ module Homebrew HOMEBREW_PREFIX.glob("lib/python*/site-packages").each do |site_packages| site_packages.each_child do |child| next unless child.directory? - # TODO: Work out a sensible way to clean up pip's, setuptools', and wheel's - # {dist,site}-info directories. Alternatively, consider always removing + # TODO: Work out a sensible way to clean up `pip`'s, `setuptools`' and `wheel`'s + # `{dist,site}-info` directories. Alternatively, consider always removing # all `-info` directories, because we may not be making use of them. next if child.basename.to_s.end_with?("-info") diff --git a/Library/Homebrew/cmd/--prefix.rb b/Library/Homebrew/cmd/--prefix.rb index eb44d4ef35..c01fa7dc17 100644 --- a/Library/Homebrew/cmd/--prefix.rb +++ b/Library/Homebrew/cmd/--prefix.rb @@ -95,7 +95,7 @@ module Homebrew dirs = HOMEBREW_PREFIX.subdirs.map { |dir| dir.basename.to_s } dirs -= %w[Library Cellar Caskroom .git] - # Exclude cache, logs, and repository, if they are located under the prefix. + # Exclude cache, logs and repository, if they are located under the prefix. [HOMEBREW_CACHE, HOMEBREW_LOGS, HOMEBREW_REPOSITORY].each do |dir| dirs.delete dir.relative_path_from(HOMEBREW_PREFIX).to_s end diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb index a6a7eb6a3e..72170324a6 100644 --- a/Library/Homebrew/cmd/outdated.rb +++ b/Library/Homebrew/cmd/outdated.rb @@ -13,7 +13,7 @@ module Homebrew cmd_args do description <<~EOS List installed casks and formulae that have an updated version available. By default, version - information is displayed in interactive shells, and suppressed otherwise. + information is displayed in interactive shells and suppressed otherwise. EOS switch "-q", "--quiet", description: "List only the names of outdated kegs (takes precedence over `--verbose`)." diff --git a/Library/Homebrew/cmd/update-report.rb b/Library/Homebrew/cmd/update-report.rb index f81fc26603..0ab6fbabf9 100644 --- a/Library/Homebrew/cmd/update-report.rb +++ b/Library/Homebrew/cmd/update-report.rb @@ -756,7 +756,7 @@ class ReporterHub def dump(auto_update: false) report_all = ENV["HOMEBREW_UPDATE_REPORT_ALL_FORMULAE"].present? if report_all && !Homebrew::EnvConfig.no_install_from_api? - odisabled "HOMEBREW_UPDATE_REPORT_ALL_FORMULAE" + odisabled "`HOMEBREW_UPDATE_REPORT_ALL_FORMULAE`" opoo "This will not report all formulae because Homebrew cannot get this data from the API." report_all = false end diff --git a/Library/Homebrew/compilers.rb b/Library/Homebrew/compilers.rb index 03e8d3e806..62cbfbe29e 100644 --- a/Library/Homebrew/compilers.rb +++ b/Library/Homebrew/compilers.rb @@ -65,7 +65,6 @@ class CompilerFailure type == compiler.type && version_matched end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: #{type} #{version}>" diff --git a/Library/Homebrew/cxxstdlib.rb b/Library/Homebrew/cxxstdlib.rb index 1745e51c0e..a87523c472 100644 --- a/Library/Homebrew/cxxstdlib.rb +++ b/Library/Homebrew/cxxstdlib.rb @@ -22,7 +22,6 @@ class CxxStdlib type.to_s.gsub(/cxx$/, "c++") end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: #{compiler} #{type}>" diff --git a/Library/Homebrew/dependencies.rb b/Library/Homebrew/dependencies.rb index a38912a036..6eec3de36e 100644 --- a/Library/Homebrew/dependencies.rb +++ b/Library/Homebrew/dependencies.rb @@ -35,7 +35,6 @@ class Dependencies < SimpleDelegator self.class.new(*__getobj__.reject { |dep| dep.uses_from_macos? && dep.use_macos_install? }) end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: #{__getobj__}>" @@ -62,7 +61,6 @@ class Requirements < SimpleDelegator self end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: {#{__getobj__.to_a.join(", ")}}>" diff --git a/Library/Homebrew/dependencies_helpers.rb b/Library/Homebrew/dependencies_helpers.rb index fa6b3b2b4b..7b0f4dc0e5 100644 --- a/Library/Homebrew/dependencies_helpers.rb +++ b/Library/Homebrew/dependencies_helpers.rb @@ -33,7 +33,7 @@ module DependenciesHelpers end # If a tap isn't installed, we can't find the dependencies of one of - # its formulae, and an exception will be thrown if we try. + # its formulae and an exception will be thrown if we try. Dependency.keep_but_prune_recursive_deps if klass == Dependency && dep.tap && !dep.tap.installed? end end diff --git a/Library/Homebrew/dependency.rb b/Library/Homebrew/dependency.rb index 2e03e08ee3..aff96c1840 100644 --- a/Library/Homebrew/dependency.rb +++ b/Library/Homebrew/dependency.rb @@ -4,6 +4,8 @@ require "dependable" # A dependency on another Homebrew formula. +# +# @api internal class Dependency extend Forwardable include Dependable @@ -94,11 +96,9 @@ class Dependency false end - # @!visibility private sig { returns(String) } def to_s = name - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: #{name.inspect} #{tags.inspect}>" @@ -115,6 +115,8 @@ class Dependency # the list. # The default filter, which is applied when a block is not given, omits # optionals and recommends based on what the dependent has asked for + # + # @api internal def expand(dependent, deps = dependent.deps, cache_key: nil, &block) # Keep track dependencies to avoid infinite cyclic dependency recursion. @expand_stack ||= [] @@ -181,6 +183,8 @@ class Dependency end # Keep a dependency, but prune its dependencies. + # + # @api internal sig { void } def keep_but_prune_recursive_deps throw(:action, :keep_but_prune_recursive_deps) @@ -282,7 +286,6 @@ class UsesFromMacOSDependency < Dependency self.class.new(formula.full_name.to_s, tags, bounds:) end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: #{name.inspect} #{tags.inspect} #{bounds.inspect}>" diff --git a/Library/Homebrew/dependency_collector.rb b/Library/Homebrew/dependency_collector.rb index 4d03ada7f8..8a27e3958a 100644 --- a/Library/Homebrew/dependency_collector.rb +++ b/Library/Homebrew/dependency_collector.rb @@ -7,13 +7,13 @@ require "requirement" require "requirements" require "extend/cachable" -## A dependency is a formula that another formula needs to install. -## A requirement is something other than a formula that another formula -## needs to be present. This includes external language modules, -## command-line tools in the path, or any arbitrary predicate. -## -## The `depends_on` method in the formula DSL is used to declare -## dependencies and requirements. +# A dependency is a formula that another formula needs to install. +# A requirement is something other than a formula that another formula +# needs to be present. This includes external language modules, +# command-line tools in the path, or any arbitrary predicate. +# +# The `depends_on` method in the formula DSL is used to declare +# dependencies and requirements. # This class is used by `depends_on` in the formula DSL to turn dependency # specifications into the proper kinds of dependencies and requirements. diff --git a/Library/Homebrew/dev-cmd/extract.rb b/Library/Homebrew/dev-cmd/extract.rb index 3735541c8a..40144dd571 100644 --- a/Library/Homebrew/dev-cmd/extract.rb +++ b/Library/Homebrew/dev-cmd/extract.rb @@ -98,7 +98,7 @@ module Homebrew end odie "Could not find #{name}! The formula or version may not have existed." if test_formula.nil? else - # Search in the root directory of as well as recursively in all of its subdirectories + # Search in the root directory of `repo` as well as recursively in all of its subdirectories. files = Dir[repo/"{,**/}"].filter_map do |dir| Pathname.glob("#{dir}/#{name}.rb").find(&:file?) end diff --git a/Library/Homebrew/dev-cmd/pr-pull.rb b/Library/Homebrew/dev-cmd/pr-pull.rb index c08badc32f..6e6210acd0 100644 --- a/Library/Homebrew/dev-cmd/pr-pull.rb +++ b/Library/Homebrew/dev-cmd/pr-pull.rb @@ -15,7 +15,7 @@ module Homebrew cmd_args do description <<~EOS - Download and publish bottles, and apply the bottle commit from a + Download and publish bottles and apply the bottle commit from a pull request with artifacts generated by GitHub Actions. Requires write access to the repository. EOS @@ -187,7 +187,7 @@ module Homebrew end end - # Separates a commit message into subject, body, and trailers. + # Separates a commit message into subject, body and trailers. def separate_commit_message(message) subject = message.lines.first.strip @@ -337,7 +337,7 @@ module Homebrew new_package = package_file.read bump_subject = determine_bump_subject(old_package, new_package, package_file, reason:) - # Commit with the new subject, body, and trailers. + # Commit with the new subject, body and trailers. safe_system("git", "-C", git_repo.pathname, "commit", "--quiet", "-m", bump_subject, "-m", messages.join("\n"), "-m", trailers.join("\n"), "--author", original_author, "--date", original_date, "--", file) diff --git a/Library/Homebrew/dev-cmd/rubydoc.rb b/Library/Homebrew/dev-cmd/rubydoc.rb index 584e298297..e7ca0e9d59 100644 --- a/Library/Homebrew/dev-cmd/rubydoc.rb +++ b/Library/Homebrew/dev-cmd/rubydoc.rb @@ -20,16 +20,18 @@ module Homebrew def run Homebrew.install_bundler_gems!(groups: ["doc"]) - HOMEBREW_LIBRARY_PATH.cd do + HOMEBREW_LIBRARY_PATH.cd do |dir| no_api_args = if args.only_public? ["--hide-api", "private", "--hide-api", "internal"] else [] end - system "bundle", "exec", "yard", "doc", "--output", "doc", *no_api_args + output_dir = dir/"doc" - exec_browser "file://#{HOMEBREW_LIBRARY_PATH}/doc/index.html" if args.open? + safe_system "bundle", "exec", "yard", "doc", "--fail-on-warning", *no_api_args, "--output", output_dir + + exec_browser "file://#{output_dir}/index.html" if args.open? end end end diff --git a/Library/Homebrew/dev-cmd/tap-new.rb b/Library/Homebrew/dev-cmd/tap-new.rb index 84d0d415a6..8278731722 100644 --- a/Library/Homebrew/dev-cmd/tap-new.rb +++ b/Library/Homebrew/dev-cmd/tap-new.rb @@ -46,6 +46,8 @@ module Homebrew (tap.path/"Formula").mkpath + # FIXME: https://github.com/errata-ai/vale/issues/818 + # readme = <<~MARKDOWN # #{titleized_user} #{titleized_repo} @@ -59,6 +61,7 @@ module Homebrew `brew help`, `man brew` or check [Homebrew's documentation](https://docs.brew.sh). MARKDOWN + # write_path(tap, "README.md", readme) actions_main = <<~YAML diff --git a/Library/Homebrew/dev-cmd/tests.rb b/Library/Homebrew/dev-cmd/tests.rb index 0a3a99b2d1..60845d6cc2 100644 --- a/Library/Homebrew/dev-cmd/tests.rb +++ b/Library/Homebrew/dev-cmd/tests.rb @@ -22,13 +22,13 @@ module Homebrew description: "Include tests that use the GitHub API and tests that use any of the taps for " \ "official external commands." switch "--debug", - description: "Enable debugging using ruby/debug, or surface the standard `odebug` output." + description: "Enable debugging using `ruby/debug`, or surface the standard `odebug` output." switch "--changed", description: "Only runs tests on files that were changed from the master branch." switch "--fail-fast", description: "Exit early on the first failing test." flag "--only=", - description: "Run only `_spec.rb`. Appending `:` will start at a " \ + description: "Run only `_spec.rb`. Appending `:` will start at a " \ "specific line." flag "--profile=", description: "Run the test suite serially to find the slowest tests." @@ -145,7 +145,10 @@ module Homebrew end # Workaround for: + # + # ``` # ruby: no -r allowed while running setuid (SecurityError) + # ``` Process::UID.change_privilege(Process.euid) if Process.euid != Process.uid if parallel diff --git a/Library/Homebrew/dev-cmd/update-test.rb b/Library/Homebrew/dev-cmd/update-test.rb index c2b637f686..1b9193097e 100644 --- a/Library/Homebrew/dev-cmd/update-test.rb +++ b/Library/Homebrew/dev-cmd/update-test.rb @@ -116,7 +116,7 @@ module Homebrew # update ENV["PATH"] ENV["PATH"] = PATH.new(ENV.fetch("PATH")).prepend(curdir/"bin").to_s - # run brew help to install portable-ruby (if needed) + # Run `brew help` to install `portable-ruby` (if needed). quiet_system "brew", "help" # run brew update diff --git a/Library/Homebrew/diagnostic.rb b/Library/Homebrew/diagnostic.rb index c764977dd8..be12eb049c 100644 --- a/Library/Homebrew/diagnostic.rb +++ b/Library/Homebrew/diagnostic.rb @@ -221,7 +221,7 @@ module Homebrew __check_stray_files "/usr/local/lib", "*.dylib", allow_list, <<~EOS Unbrewed dylibs were found in /usr/local/lib. If you didn't put them there on purpose they could cause problems when - building Homebrew formulae, and may need to be deleted. + building Homebrew formulae and may need to be deleted. Unexpected dylibs: EOS @@ -246,7 +246,7 @@ module Homebrew __check_stray_files "/usr/local/lib", "*.a", allow_list, <<~EOS Unbrewed static libraries were found in /usr/local/lib. If you didn't put them there on purpose they could cause problems when - building Homebrew formulae, and may need to be deleted. + building Homebrew formulae and may need to be deleted. Unexpected static libraries: EOS @@ -266,7 +266,7 @@ module Homebrew __check_stray_files "/usr/local/lib/pkgconfig", "*.pc", allow_list, <<~EOS Unbrewed '.pc' files were found in /usr/local/lib/pkgconfig. If you didn't put them there on purpose they could cause problems when - building Homebrew formulae, and may need to be deleted. + building Homebrew formulae and may need to be deleted. Unexpected '.pc' files: EOS @@ -287,7 +287,7 @@ module Homebrew __check_stray_files "/usr/local/lib", "*.la", allow_list, <<~EOS Unbrewed '.la' files were found in /usr/local/lib. If you didn't put them there on purpose they could cause problems when - building Homebrew formulae, and may need to be deleted. + building Homebrew formulae and may need to be deleted. Unexpected '.la' files: EOS @@ -306,7 +306,7 @@ module Homebrew __check_stray_files "/usr/local/include", "**/*.h", allow_list, <<~EOS Unbrewed header files were found in /usr/local/include. If you didn't put them there on purpose they could cause problems when - building Homebrew formulae, and may need to be deleted. + building Homebrew formulae and may need to be deleted. Unexpected header files: EOS @@ -491,7 +491,7 @@ module Homebrew <<~EOS Git could not be found in your PATH. - Homebrew uses Git for several internal functions, and some formulae use Git + Homebrew uses Git for several internal functions and some formulae use Git checkouts instead of stable tarballs. You may want to install Git: brew install git EOS diff --git a/Library/Homebrew/download_strategy.rb b/Library/Homebrew/download_strategy.rb index 2252caeb6e..e4c9aa0038 100644 --- a/Library/Homebrew/download_strategy.rb +++ b/Library/Homebrew/download_strategy.rb @@ -77,11 +77,9 @@ class AbstractDownloadStrategy end # Disable any output during downloading. - # - # @deprecated sig { void } def shutup! - odeprecated "AbstractDownloadStrategy#shutup!", "AbstractDownloadStrategy#quiet!" + odeprecated "`AbstractDownloadStrategy#shutup!`", "`AbstractDownloadStrategy#quiet!`" quiet! end @@ -125,7 +123,6 @@ class AbstractDownloadStrategy end private :chdir - # @!attribute [r] source_modified_time # Returns the most recent modified time for all files in the current working directory after stage. # # @api public @@ -236,9 +233,7 @@ class VCSDownloadStrategy < AbstractDownloadStrategy version.respond_to?(:head?) && version.head? end - # @!attribute [r] last_commit - # Return last commit's unique identifier for the repository. - # Return most recent modified timestamp unless overridden. + # Return the most recent modified timestamp. # # @api public sig { returns(String) } @@ -733,7 +728,8 @@ class SubversionDownloadStrategy < VCSDownloadStrategy super end - # @see AbstractDownloadStrategy#source_modified_time + # Returns the most recent modified time for all files in the current working directory after stage. + # # @api public sig { returns(Time) } def source_modified_time @@ -747,7 +743,8 @@ class SubversionDownloadStrategy < VCSDownloadStrategy Time.parse time end - # @see VCSDownloadStrategy#last_commit + # Return last commit's unique identifier for the repository. + # # @api public sig { returns(String) } def last_commit @@ -847,7 +844,8 @@ class GitDownloadStrategy < VCSDownloadStrategy @ref ||= "master" end - # @see AbstractDownloadStrategy#source_modified_time + # Returns the most recent modified time for all files in the current working directory after stage. + # # @api public sig { returns(Time) } def source_modified_time @@ -855,7 +853,8 @@ class GitDownloadStrategy < VCSDownloadStrategy Time.parse(out) end - # @see VCSDownloadStrategy#last_commit + # Return last commit's unique identifier for the repository. + # # @api public sig { returns(String) } def last_commit @@ -932,8 +931,8 @@ class GitDownloadStrategy < VCSDownloadStrategy args << "--no-checkout" << "--filter=blob:none" if partial_clone_sparse_checkout? - args << "--config" << "advice.detachedHead=false" # silences detached head warning - args << "--config" << "core.fsmonitor=false" # prevent fsmonitor from watching this repo + args << "--config" << "advice.detachedHead=false" # Silences “detached head” warning. + args << "--config" << "core.fsmonitor=false" # Prevent `fsmonitor` from watching this repository. args << @url << cached_location.to_s end @@ -1165,7 +1164,8 @@ class CVSDownloadStrategy < VCSDownloadStrategy end end - # @see AbstractDownloadStrategy#source_modified_time + # Returns the most recent modified time for all files in the current working directory after stage. + # # @api public sig { returns(Time) } def source_modified_time @@ -1240,7 +1240,8 @@ class MercurialDownloadStrategy < VCSDownloadStrategy @url = @url.sub(%r{^hg://}, "") end - # @see AbstractDownloadStrategy#source_modified_time + # Returns the most recent modified time for all files in the current working directory after stage. + # # @api public sig { returns(Time) } def source_modified_time @@ -1250,7 +1251,8 @@ class MercurialDownloadStrategy < VCSDownloadStrategy Time.parse(out) end - # @see VCSDownloadStrategy#last_commit + # Return last commit's unique identifier for the repository. + # # @api public sig { returns(String) } def last_commit @@ -1327,7 +1329,8 @@ class BazaarDownloadStrategy < VCSDownloadStrategy @url = @url.sub(%r{^bzr://}, "") end - # @see AbstractDownloadStrategy#source_modified_time + # Returns the most recent modified time for all files in the current working directory after stage. + # # @api public sig { returns(Time) } def source_modified_time @@ -1338,7 +1341,8 @@ class BazaarDownloadStrategy < VCSDownloadStrategy Time.parse(timestamp) end - # @see VCSDownloadStrategy#last_commit + # Return last commit's unique identifier for the repository. + # # @api public sig { returns(String) } def last_commit @@ -1390,7 +1394,8 @@ class FossilDownloadStrategy < VCSDownloadStrategy @url = @url.sub(%r{^fossil://}, "") end - # @see AbstractDownloadStrategy#source_modified_time + # Returns the most recent modified time for all files in the current working directory after stage. + # # @api public sig { returns(Time) } def source_modified_time @@ -1398,7 +1403,8 @@ class FossilDownloadStrategy < VCSDownloadStrategy Time.parse(out[/^uuid: +\h+ (.+)$/, 1]) end - # @see VCSDownloadStrategy#last_commit + # Return last commit's unique identifier for the repository. + # # @api public sig { returns(String) } def last_commit diff --git a/Library/Homebrew/exceptions.rb b/Library/Homebrew/exceptions.rb index ccb0daa382..bdcc50ef24 100644 --- a/Library/Homebrew/exceptions.rb +++ b/Library/Homebrew/exceptions.rb @@ -16,7 +16,6 @@ class UsageError < RuntimeError @reason = reason end - # @!visibility private sig { returns(String) } def to_s s = "Invalid usage" @@ -109,7 +108,6 @@ class FormulaOrCaskUnavailableError < RuntimeError "Did you mean #{similar_formula_names.to_sentence two_words_connector: " or ", last_word_connector: " or "}?" end - # @!visibility private sig { returns(String) } def to_s s = "No available formula or cask with the name \"#{name}\". #{did_you_mean}".strip @@ -129,7 +127,6 @@ class TapFormulaOrCaskUnavailableError < FormulaOrCaskUnavailableError @tap = tap end - # @!visibility private sig { returns(String) } def to_s s = super @@ -149,7 +146,6 @@ class FormulaUnavailableError < FormulaOrCaskUnavailableError " (dependency of #{dependent})" if dependent && dependent != name end - # @!visibility private sig { returns(String) } def to_s "No available formula with the name \"#{name}\"#{dependent_s}. #{did_you_mean}".strip @@ -160,7 +156,6 @@ end module FormulaClassUnavailableErrorModule attr_reader :path, :class_name, :class_list - # @!visibility private sig { returns(String) } def to_s s = super @@ -204,7 +199,6 @@ end module FormulaUnreadableErrorModule attr_reader :formula_error - # @!visibility private sig { returns(String) } def to_s "#{name}: " + formula_error.to_s @@ -233,7 +227,6 @@ class TapFormulaUnavailableError < FormulaUnavailableError super "#{tap}/#{name}" end - # @!visibility private sig { returns(String) } def to_s s = super @@ -572,7 +565,7 @@ class UnbottledError < RuntimeError end end -# Raised by Homebrew.install, Homebrew.reinstall, and Homebrew.upgrade +# Raised by `Homebrew.install`, `Homebrew.reinstall` and `Homebrew.upgrade` # if the user passes any flags/environment that would case a bottle-only # installation on a system without build tools to fail. class BuildFlagsError < RuntimeError diff --git a/Library/Homebrew/extend/ENV.rb b/Library/Homebrew/extend/ENV.rb index 051acbb11a..b7a9afb644 100644 --- a/Library/Homebrew/extend/ENV.rb +++ b/Library/Homebrew/extend/ENV.rb @@ -17,10 +17,16 @@ module Kernel private :superenv? end +# # @!parse -# # ENV is not actually a class, but this makes `YARD` happy -# # @see https://rubydoc.info/stdlib/core/ENV ENV core documentation -# class ENV; end +# # `ENV` is not actually a class, but this makes YARD happy +# # @see https://rubydoc.info/stdlib/core/ENV +# # ENV core documentation +# # @see Superenv +# # @see Stdenv +# class ENV; end +# + module EnvActivation sig { params(env: T.nilable(String)).void } def activate_extensions!(env: nil) diff --git a/Library/Homebrew/extend/ENV.rbi b/Library/Homebrew/extend/ENV.rbi index 0c7c926da8..dca2af30b3 100644 --- a/Library/Homebrew/extend/ENV.rbi +++ b/Library/Homebrew/extend/ENV.rbi @@ -1,5 +1,6 @@ # typed: strict +# @!visibility private module EnvMethods include Kernel @@ -39,6 +40,7 @@ module EnvActivation include Superenv end +# @!visibility private class Sorbet module Private module Static diff --git a/Library/Homebrew/extend/ENV/shared.rbi b/Library/Homebrew/extend/ENV/shared.rbi index b1eac4cd3e..1a6b66af46 100644 --- a/Library/Homebrew/extend/ENV/shared.rbi +++ b/Library/Homebrew/extend/ENV/shared.rbi @@ -4,6 +4,7 @@ module SharedEnvExtension include EnvMethods end +# @!visibility private class Sorbet module Private module Static diff --git a/Library/Homebrew/extend/array.rb b/Library/Homebrew/extend/array.rb index 152033304b..e68b1277a1 100644 --- a/Library/Homebrew/extend/array.rb +++ b/Library/Homebrew/extend/array.rb @@ -2,59 +2,72 @@ # frozen_string_literal: true class Array - # Equal to self[1]. + # Equal to `self[1]`. # - # %w( a b c d e ).second # => "b" + # ### Example + # + # ```ruby + # %w( a b c d e ).second # => "b" + # ``` def second = self[1] - # Equal to self[2]. + # Equal to `self[2]`. # - # %w( a b c d e ).third # => "c" + # ### Example + # + # ```ruby + # %w( a b c d e ).third # => "c" + # ``` def third = self[2] - # Equal to self[3]. + # Equal to `self[3]`. # - # %w( a b c d e ).fourth # => "d" + # ### Example + # + # ```ruby + # %w( a b c d e ).fourth # => "d" + # ``` def fourth = self[3] - # Equal to self[4]. + # Equal to `self[4]`. # - # %w( a b c d e ).fifth # => "e" + # ### Example + # + # ```ruby + # %w( a b c d e ).fifth # => "e" + # ``` def fifth = self[4] # Converts the array to a comma-separated sentence where the last element is # joined by the connector word. # - # You can pass the following kwargs to change the default behavior: + # ### Examples # - # * :words_connector - The sign or word used to join all but the last - # element in arrays with three or more elements (default: ", "). - # * :last_word_connector - The sign or word used to join the last element - # in arrays with three or more elements (default: ", and "). - # * :two_words_connector - The sign or word used to join the elements - # in arrays with two elements (default: " and "). + # ```ruby + # [].to_sentence # => "" + # ['one'].to_sentence # => "one" + # ['one', 'two'].to_sentence # => "one and two" + # ['one', 'two', 'three'].to_sentence # => "one, two and three" + # ['one', 'two'].to_sentence(two_words_connector: '-') + # # => "one-two" + # ``` # - # ==== Examples + # ``` + # ['one', 'two', 'three'].to_sentence(words_connector: ' or ', last_word_connector: ' or at least ') + # # => "one or two or at least three" + # ``` # - # [].to_sentence # => "" - # ['one'].to_sentence # => "one" - # ['one', 'two'].to_sentence # => "one and two" - # ['one', 'two', 'three'].to_sentence # => "one, two, and three" - # ['one', 'two'].to_sentence(two_words_connector: '-') - # # => "one-two" - # - # ['one', 'two', 'three'].to_sentence(words_connector: ' or ', last_word_connector: ' or at least ') - # # => "one or two or at least three" # @see https://github.com/rails/rails/blob/v7.0.4.2/activesupport/lib/active_support/core_ext/array/conversions.rb#L8-L84 # ActiveSupport Array#to_sentence monkey-patch # + # # Copyright (c) David Heinemeier Hansson # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the # "Software"), to deal in the Software without restriction, including # without limitation the rights to use, copy, modify, merge, publish, - # distribute, sublicense, and/or sell copies of the Software, and to + # distribute, sublicense and/or sell copies of the Software and to # permit persons to whom the Software is furnished to do so, subject to # the following conditions: # @@ -68,6 +81,14 @@ class Array # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + # + # + # @param [String] words_connector The sign or word used to join all but the last + # element in arrays with three or more elements (default: `", "`). + # @param [String] last_word_connector The sign or word used to join the last element + # in arrays with three or more elements (default: `" and "`). + # @param [String] two_words_connector The sign or word used to join the elements + # in arrays with two elements (default: `" and "`). sig { params(words_connector: String, two_words_connector: String, last_word_connector: String).returns(String) } def to_sentence(words_connector: ", ", two_words_connector: " and ", last_word_connector: " and ") case length diff --git a/Library/Homebrew/extend/blank.rb b/Library/Homebrew/extend/blank.rb index 9eb738e69d..85c5ea55b4 100644 --- a/Library/Homebrew/extend/blank.rb +++ b/Library/Homebrew/extend/blank.rb @@ -3,15 +3,20 @@ class Object # An object is blank if it's false, empty, or a whitespace string. - # For example, +nil+, '', ' ', [], {}, and +false+ are all blank. # - # This simplifies + # For example, `nil`, `''`, `' '`, `[]`, `{}` and `false` are all blank. # - # !address || address.empty? + # ### Example # - # to + # ```ruby + # !address || address.empty? + # ``` # - # address.blank? + # can be simplified to + # + # ```ruby + # address.blank? + # ``` sig { returns(T::Boolean) } def blank? respond_to?(:empty?) ? !!T.unsafe(self).empty? : false @@ -21,20 +26,23 @@ class Object sig { returns(T::Boolean) } def present? = !blank? - # Returns the receiver if it's present otherwise returns +nil+. - # object.presence is equivalent to + # Returns the receiver if it's present, otherwise returns `nil`. # - # object.present? ? object : nil + # `object.presence` is equivalent to `object.present? ? object : nil`. # - # For example, something like + # ### Example # - # state = params[:state] if params[:state].present? - # country = params[:country] if params[:country].present? - # region = state || country || 'US' + # ```ruby + # state = params[:state] if params[:state].present? + # country = params[:country] if params[:country].present? + # region = state || country || 'US' + # ``` # - # becomes + # can be simplified to # - # region = params[:state].presence || params[:country].presence || 'US' + # ```ruby + # region = params[:state].presence || params[:country].presence || 'US' + # ``` sig { returns(T.nilable(T.self_type)) } def presence self if present? @@ -42,9 +50,11 @@ class Object end class NilClass - # +nil+ is blank: + # `nil` is blank: # - # nil.blank? # => true + # ```ruby + # nil.blank? # => true + # ``` sig { returns(TrueClass) } def blank? = true @@ -53,9 +63,11 @@ class NilClass end class FalseClass - # +false+ is blank: + # `false` is blank: # - # false.blank? # => true + # ```ruby + # false.blank? # => true + # ``` sig { returns(TrueClass) } def blank? = true @@ -64,9 +76,11 @@ class FalseClass end class TrueClass - # +true+ is not blank: + # `true` is not blank: # - # true.blank? # => false + # ```ruby + # true.blank? # => false + # ``` sig { returns(FalseClass) } def blank? = false @@ -77,11 +91,12 @@ end class Array # An array is blank if it's empty: # - # [].blank? # => true - # [1,2,3].blank? # => false - # - # @return [true, false] - alias blank? empty? + # ```ruby + # [].blank? # => true + # [1,2,3].blank? # => false + # ``` + sig { returns(T::Boolean) } + def blank? = empty? sig { returns(T::Boolean) } def present? = !empty? # :nodoc: @@ -90,11 +105,13 @@ end class Hash # A hash is blank if it's empty: # - # {}.blank? # => true - # { key: 'value' }.blank? # => false # - # @return [true, false] - alias blank? empty? + # ```ruby + # {}.blank? # => true + # { key: 'value' }.blank? # => false + # ``` + sig { returns(T::Boolean) } + def blank? = empty? sig { returns(T::Boolean) } def present? = !empty? # :nodoc: @@ -103,9 +120,12 @@ end class Symbol # A Symbol is blank if it's empty: # - # :''.blank? # => true - # :symbol.blank? # => false - alias blank? empty? + # ```ruby + # :''.blank? # => true + # :symbol.blank? # => false + # ``` + sig { returns(T::Boolean) } + def blank? = empty? sig { returns(T::Boolean) } def present? = !empty? # :nodoc: @@ -122,14 +142,18 @@ class String # A string is blank if it's empty or contains whitespaces only: # - # ''.blank? # => true - # ' '.blank? # => true - # "\t\n\r".blank? # => true - # ' blah '.blank? # => false + # ```ruby + # ''.blank? # => true + # ' '.blank? # => true + # "\t\n\r".blank? # => true + # ' blah '.blank? # => false + # ``` # # Unicode whitespace is supported: # - # "\u00a0".blank? # => true + # ```ruby + # "\u00a0".blank? # => true + # ``` sig { returns(T::Boolean) } def blank? # The regexp that matches blank strings is expensive. For the case of empty @@ -150,8 +174,10 @@ end class Numeric # :nodoc: # No number is blank: # - # 1.blank? # => false - # 0.blank? # => false + # ```ruby + # 1.blank? # => false + # 0.blank? # => false + # ``` sig { returns(FalseClass) } def blank? = false @@ -162,7 +188,9 @@ end class Time # :nodoc: # No Time is blank: # - # Time.now.blank? # => false + # ```ruby + # Time.now.blank? # => false + # ``` sig { returns(FalseClass) } def blank? = false diff --git a/Library/Homebrew/extend/enumerable.rb b/Library/Homebrew/extend/enumerable.rb index 77b499b2dd..5f8ca22f17 100644 --- a/Library/Homebrew/extend/enumerable.rb +++ b/Library/Homebrew/extend/enumerable.rb @@ -2,7 +2,7 @@ # frozen_string_literal: true module Enumerable - # The negative of the Enumerable#include?. Returns +true+ if the + # The negative of the {Enumerable#include?}. Returns `true` if the # collection does not include the object. sig { params(object: T.untyped).returns(T::Boolean) } def exclude?(object) = !include?(object) @@ -10,21 +10,29 @@ module Enumerable # Returns a new +Array+ without the blank items. # Uses Object#blank? for determining if an item is blank. # - # [1, "", nil, 2, " ", [], {}, false, true].compact_blank - # # => [1, 2, true] + # ### Examples # - # Set.new([nil, "", 1, false]).compact_blank - # # => [1] + # ``` + # [1, "", nil, 2, " ", [], {}, false, true].compact_blank + # # => [1, 2, true] + # ``` # - # When called on a +Hash+, returns a new +Hash+ without the blank values. + # ```ruby + # Set.new([nil, "", 1, false]).compact_blank + # # => [1] + # ``` # - # { a: "", b: 1, c: nil, d: [], e: false, f: true }.compact_blank - # # => { b: 1, f: true } + # When called on a {Hash}, returns a new {Hash} without the blank values. + # + # ```ruby + # { a: "", b: 1, c: nil, d: [], e: false, f: true }.compact_blank + # # => { b: 1, f: true } + # ``` sig { returns(T.self_type) } def compact_blank = T.unsafe(self).reject(&:blank?) end class Hash - # Hash#reject has its own definition, so this needs one too. + # {Hash#reject} has its own definition, so this needs one too. def compact_blank = reject { |_k, v| T.unsafe(v).blank? } end diff --git a/Library/Homebrew/extend/hash/deep_merge.rb b/Library/Homebrew/extend/hash/deep_merge.rb index 01ecbe9260..527e36076b 100644 --- a/Library/Homebrew/extend/hash/deep_merge.rb +++ b/Library/Homebrew/extend/hash/deep_merge.rb @@ -2,25 +2,31 @@ # frozen_string_literal: true class Hash - # Returns a new hash with +self+ and +other_hash+ merged recursively. + # Returns a new hash with `self` and `other_hash` merged recursively. # - # h1 = { a: true, b: { c: [1, 2, 3] } } - # h2 = { a: false, b: { x: [3, 4, 5] } } + # ### Examples # - # h1.deep_merge(h2) # => { a: false, b: { c: [1, 2, 3], x: [3, 4, 5] } } + # ```ruby + # h1 = { a: true, b: { c: [1, 2, 3] } } + # h2 = { a: false, b: { x: [3, 4, 5] } } + # + # h1.deep_merge(h2) # => { a: false, b: { c: [1, 2, 3], x: [3, 4, 5] } } + # ``` # # Like with Hash#merge in the standard library, a block can be provided # to merge values: # - # h1 = { a: 100, b: 200, c: { c1: 100 } } - # h2 = { b: 250, c: { c1: 200 } } - # h1.deep_merge(h2) { |key, this_val, other_val| this_val + other_val } - # # => { a: 100, b: 450, c: { c1: 300 } } + # ```ruby + # h1 = { a: 100, b: 200, c: { c1: 100 } } + # h2 = { b: 250, c: { c1: 200 } } + # h1.deep_merge(h2) { |key, this_val, other_val| this_val + other_val } + # # => { a: 100, b: 450, c: { c1: 300 } } + # ``` def deep_merge(other_hash, &block) dup.deep_merge!(other_hash, &block) end - # Same as +deep_merge+, but modifies +self+. + # Same as {#deep_merge}, but modifies `self`. def deep_merge!(other_hash, &block) merge!(other_hash) do |key, this_val, other_val| if T.unsafe(this_val).is_a?(Hash) && other_val.is_a?(Hash) diff --git a/Library/Homebrew/extend/hash/deep_transform_values.rb b/Library/Homebrew/extend/hash/deep_transform_values.rb index 2787efc1f6..be366f1b14 100644 --- a/Library/Homebrew/extend/hash/deep_transform_values.rb +++ b/Library/Homebrew/extend/hash/deep_transform_values.rb @@ -6,11 +6,14 @@ class Hash # This includes the values from the root hash and from all # nested hashes and arrays. # - # @example - # hash = { person: { name: 'Rob', age: '28' } } + # ### Example # - # hash.deep_transform_values{ |value| value.to_s.upcase } - # # => {person: {name: "ROB", age: "28"}} + # ```ruby + # hash = { person: { name: 'Rob', age: '28' } } + # + # hash.deep_transform_values{ |value| value.to_s.upcase } + # # => {person: {name: "ROB", age: "28"}} + # ``` def deep_transform_values(&block) = _deep_transform_values_in_object(self, &block) # Destructively converts all values by using the block operation. diff --git a/Library/Homebrew/extend/hash/keys.rb b/Library/Homebrew/extend/hash/keys.rb index 06878a4ce0..fc0cbfbe59 100644 --- a/Library/Homebrew/extend/hash/keys.rb +++ b/Library/Homebrew/extend/hash/keys.rb @@ -5,14 +5,18 @@ class Hash # Validates all keys in a hash match `*valid_keys`, raising # `ArgumentError` on a mismatch. # - # Note that keys are treated differently than HashWithIndifferentAccess, + # Note that keys are treated differently than `HashWithIndifferentAccess`, # meaning that string and symbol keys will not match. # - # { name: 'Rob', years: '28' }.assert_valid_keys(:name, :age) - # # => raises "ArgumentError: Unknown key: :years. Valid keys are: :name, :age" - # { name: 'Rob', age: '28' }.assert_valid_keys('name', 'age') - # # => raises "ArgumentError: Unknown key: :name. Valid keys are: 'name', 'age'" - # { name: 'Rob', age: '28' }.assert_valid_keys(:name, :age) # => passes, raises nothing + # ### Example# + # + # ```ruby + # { name: 'Rob', years: '28' }.assert_valid_keys(:name, :age) + # # => raises "ArgumentError: Unknown key: :years. Valid keys are: :name, :age" + # { name: 'Rob', age: '28' }.assert_valid_keys('name', 'age') + # # => raises "ArgumentError: Unknown key: :name. Valid keys are: 'name', 'age'" + # { name: 'Rob', age: '28' }.assert_valid_keys(:name, :age) # => passes, raises nothing + # ``` sig { params(valid_keys: T.untyped).void } def assert_valid_keys(*valid_keys) valid_keys.flatten! @@ -28,10 +32,14 @@ class Hash # This includes the keys from the root hash and from all # nested hashes and arrays. # - # hash = { person: { name: 'Rob', age: '28' } } + # ### Example # - # hash.deep_transform_keys{ |key| key.to_s.upcase } - # # => {"PERSON"=>{"NAME"=>"Rob", "AGE"=>"28"}} + # ```ruby + # hash = { person: { name: 'Rob', age: '28' } } + # + # hash.deep_transform_keys{ |key| key.to_s.upcase } + # # => {"PERSON"=>{"NAME"=>"Rob", "AGE"=>"28"}} + # ``` def deep_transform_keys(&block) = _deep_transform_keys_in_object(self, &block) # Destructively converts all keys by using the block operation. @@ -43,10 +51,14 @@ class Hash # This includes the keys from the root hash and from all # nested hashes and arrays. # - # hash = { person: { name: 'Rob', age: '28' } } + # ### Example # - # hash.deep_stringify_keys - # # => {"person"=>{"name"=>"Rob", "age"=>"28"}} + # ```ruby + # hash = { person: { name: 'Rob', age: '28' } } + # + # hash.deep_stringify_keys + # # => {"person"=>{"name"=>"Rob", "age"=>"28"}} + # ``` def deep_stringify_keys = T.unsafe(self).deep_transform_keys(&:to_s) # Destructively converts all keys to strings. @@ -55,13 +67,17 @@ class Hash def deep_stringify_keys! = T.unsafe(self).deep_transform_keys!(&:to_s) # Returns a new hash with all keys converted to symbols, as long as - # they respond to +to_sym+. This includes the keys from the root hash + # they respond to `to_sym`. This includes the keys from the root hash # and from all nested hashes and arrays. # - # hash = { 'person' => { 'name' => 'Rob', 'age' => '28' } } + # ### Example # - # hash.deep_symbolize_keys - # # => {:person=>{:name=>"Rob", :age=>"28"}} + # ```ruby + # hash = { 'person' => { 'name' => 'Rob', 'age' => '28' } } + # + # hash.deep_symbolize_keys + # # => {:person=>{:name=>"Rob", :age=>"28"}} + # ``` def deep_symbolize_keys deep_transform_keys do |key| T.unsafe(key).to_sym @@ -71,7 +87,7 @@ class Hash end # Destructively converts all keys to symbols, as long as they respond - # to +to_sym+. This includes the keys from the root hash and from all + # to `to_sym`. This includes the keys from the root hash and from all # nested hashes and arrays. def deep_symbolize_keys! deep_transform_keys! do |key| @@ -102,7 +118,7 @@ class Hash def _deep_transform_keys_in_object!(object, &block) case object when Hash - # We can't use `each_key` here because we're updating the hash in-place + # We can't use `each_key` here because we're updating the hash in-place. object.keys.each do |key| # rubocop:disable Style/HashEachMethods value = object.delete(key) object[yield(key)] = _deep_transform_keys_in_object!(value, &block) diff --git a/Library/Homebrew/extend/kernel.rb b/Library/Homebrew/extend/kernel.rb index d9f0f2aa6f..8696c5cc6b 100644 --- a/Library/Homebrew/extend/kernel.rb +++ b/Library/Homebrew/extend/kernel.rb @@ -493,14 +493,20 @@ module Kernel end # Calls the given block with the passed environment variables - # added to ENV, then restores ENV afterwards. - # 
with_env(PATH: "/bin") do
-  #   system "echo $PATH"
-  # end
+ # added to `ENV`, then restores `ENV` afterwards. + # + # NOTE: This method is **not** thread-safe – other threads + # which happen to be scheduled during the block will also + # see these environment variables. + # + # ### Example + # + # ```ruby + # with_env(PATH: "/bin") do + # system "echo $PATH" + # end + # ``` # - # @note This method is *not* thread-safe - other threads - # which happen to be scheduled during the block will also - # see these environment variables. # @api public def with_env(hash) old_values = {} diff --git a/Library/Homebrew/extend/object/duplicable.rb b/Library/Homebrew/extend/object/duplicable.rb index d5f566cb52..a0f0462084 100644 --- a/Library/Homebrew/extend/object/duplicable.rb +++ b/Library/Homebrew/extend/object/duplicable.rb @@ -1,24 +1,30 @@ # typed: strict # frozen_string_literal: true -#-- # Most objects are cloneable, but not all. For example you can't dup methods: # -# method(:puts).dup # => TypeError: allocator undefined for Method +# ```ruby +# method(:puts).dup # => TypeError: allocator undefined for Method +# ``` # # Classes may signal their instances are not duplicable removing +dup+/+clone+ # or raising exceptions from them. So, to dup an arbitrary object you normally # use an optimistic approach and are ready to catch an exception, say: # -# arbitrary_object.dup rescue object +# ```ruby +# arbitrary_object.dup rescue object +# ``` # # Rails dups objects in a few critical spots where they are not that arbitrary. -# That rescue is very expensive (like 40 times slower than a predicate), and it +# That `rescue` is very expensive (like 40 times slower than a predicate) and it # is often triggered. # # That's why we hardcode the following cases and check duplicable? instead of # using that rescue idiom. -#++ +# rubocop:disable Layout/EmptyLines + + +# rubocop:enable Layout/EmptyLines class Object # Can you safely dup this object? # @@ -31,8 +37,10 @@ end class Method # Methods are not duplicable: # - # method(:puts).duplicable? # => false - # method(:puts).dup # => TypeError: allocator undefined for Method + # ```ruby + # method(:puts).duplicable? # => false + # method(:puts).dup # => TypeError: allocator undefined for Method + # ``` sig { returns(FalseClass) } def duplicable? = false end @@ -40,8 +48,10 @@ end class UnboundMethod # Unbound methods are not duplicable: # - # method(:puts).unbind.duplicable? # => false - # method(:puts).unbind.dup # => TypeError: allocator undefined for UnboundMethod + # ```ruby + # method(:puts).unbind.duplicable? # => false + # method(:puts).unbind.dup # => TypeError: allocator undefined for UnboundMethod + # ``` sig { returns(FalseClass) } def duplicable? = false end @@ -51,7 +61,9 @@ require "singleton" module Singleton # Singleton instances are not duplicable: # - # Class.new.include(Singleton).instance.dup # TypeError (can't dup instance of singleton + # ```ruby + # Class.new.include(Singleton).instance.dup # TypeError (can't dup instance of singleton + # ``` sig { returns(FalseClass) } def duplicable? = false end diff --git a/Library/Homebrew/extend/os/linux/install.rb b/Library/Homebrew/extend/os/linux/install.rb index 943ae7bea9..e4476a00b8 100644 --- a/Library/Homebrew/extend/os/linux/install.rb +++ b/Library/Homebrew/extend/os/linux/install.rb @@ -4,7 +4,7 @@ module Homebrew module Install # This is a list of known paths to the host dynamic linker on Linux if - # the host glibc is new enough. The symlink_ld_so method will fail if + # the host glibc is new enough. The symlink_ld_so method will fail if # the host linker cannot be found in this list. DYNAMIC_LINKERS = %w[ /lib64/ld-linux-x86-64.so.2 @@ -19,7 +19,7 @@ module Homebrew private_constant :DYNAMIC_LINKERS # We link GCC runtime libraries that are not specifically used for Fortran, - # which are linked by the GCC formula. We only use the versioned shared libraries + # which are linked by the GCC formula. We only use the versioned shared libraries # as the other shared and static libraries are only used at build time where # GCC can find its own libraries. GCC_RUNTIME_LIBS = %w[ diff --git a/Library/Homebrew/extend/os/linux/parser.rb b/Library/Homebrew/extend/os/linux/parser.rb index fcbeb67f0b..9d76e9c9b3 100644 --- a/Library/Homebrew/extend/os/linux/parser.rb +++ b/Library/Homebrew/extend/os/linux/parser.rb @@ -16,7 +16,7 @@ module Homebrew return unless @args.cask? # NOTE: We don't raise an error here because we don't want - # to print the help page or a stack trace. + # to print the help page or a stack trace. odie "Invalid `--cask` usage: Casks do not work on Linux" end end diff --git a/Library/Homebrew/extend/os/mac/diagnostic.rb b/Library/Homebrew/extend/os/mac/diagnostic.rb index 98774d3a92..6733fc0b34 100644 --- a/Library/Homebrew/extend/os/mac/diagnostic.rb +++ b/Library/Homebrew/extend/os/mac/diagnostic.rb @@ -340,7 +340,7 @@ module Homebrew else inject_file_list @found, <<~EOS libiconv files detected at a system prefix other than /usr. - Homebrew doesn't provide a libiconv formula, and expects to link against + Homebrew doesn't provide a libiconv formula and expects to link against the system version in /usr. libiconv in other prefixes can cause compile or link failure, especially if compiled with improper architectures. macOS itself never installs anything to /usr/local so diff --git a/Library/Homebrew/extend/os/mac/extend/ENV/std.rb b/Library/Homebrew/extend/os/mac/extend/ENV/std.rb index c963cf4742..37a3a335fd 100644 --- a/Library/Homebrew/extend/os/mac/extend/ENV/std.rb +++ b/Library/Homebrew/extend/os/mac/extend/ENV/std.rb @@ -27,12 +27,11 @@ module Stdenv append "LDFLAGS", "-Wl,-headerpad_max_install_names" - # sed is strict, and errors out when it encounters files with - # mixed character sets + # `sed` is strict and errors out when it encounters files with mixed character sets. delete("LC_ALL") self["LC_CTYPE"] = "C" - # Add lib and include etc. from the current macosxsdk to compiler flags: + # Add `lib` and `include` etc. from the current `macosxsdk` to compiler flags: macosxsdk(formula: @formula, testing_formula:) return unless MacOS::Xcode.without_clt? @@ -42,8 +41,8 @@ module Stdenv end def remove_macosxsdk(version = nil) - # Clear all lib and include dirs from CFLAGS, CPPFLAGS, LDFLAGS that were - # previously added by macosxsdk + # Clear all `lib` and `include` dirs from `CFLAGS`, `CPPFLAGS`, `LDFLAGS` that were + # previously added by `macosxsdk`. remove_from_cflags(/ ?-mmacosx-version-min=\d+\.\d+/) delete("CPATH") remove "LDFLAGS", "-L#{HOMEBREW_PREFIX}/lib" @@ -58,14 +57,14 @@ module Stdenv if HOMEBREW_PREFIX.to_s == "/usr/local" delete("CMAKE_PREFIX_PATH") else - # It was set in setup_build_environment, so we have to restore it here. + # It was set in `setup_build_environment`, so we have to restore it here. self["CMAKE_PREFIX_PATH"] = HOMEBREW_PREFIX.to_s end remove "CMAKE_FRAMEWORK_PATH", "#{sdk}/System/Library/Frameworks" end def macosxsdk(version = nil, formula: nil, testing_formula: false) - # Sets all needed lib and include dirs to CFLAGS, CPPFLAGS, LDFLAGS. + # Sets all needed `lib` and `include` dirs to `CFLAGS`, `CPPFLAGS`, `LDFLAGS`. remove_macosxsdk min_version = version || MacOS.version append_to_cflags("-mmacosx-version-min=#{min_version}") diff --git a/Library/Homebrew/extend/os/mac/formula_cellar_checks.rb b/Library/Homebrew/extend/os/mac/formula_cellar_checks.rb index e4ffde8f9f..e7188e670b 100644 --- a/Library/Homebrew/extend/os/mac/formula_cellar_checks.rb +++ b/Library/Homebrew/extend/os/mac/formula_cellar_checks.rb @@ -112,7 +112,7 @@ module FormulaCellarChecks <<~EOS Libraries were compiled with a flat namespace. - This can cause linker errors due to name collisions, and + This can cause linker errors due to name collisions and is often due to a bug in detecting the macOS version. #{flat_namespace_files * "\n "} EOS diff --git a/Library/Homebrew/extend/os/mac/hardware/cpu.rb b/Library/Homebrew/extend/os/mac/hardware/cpu.rb index 72df60a253..0bcd281b2c 100644 --- a/Library/Homebrew/extend/os/mac/hardware/cpu.rb +++ b/Library/Homebrew/extend/os/mac/hardware/cpu.rb @@ -83,8 +83,8 @@ module Hardware sysctl_bool("hw.optional.sse4_2") end - # NOTE: this is more reliable than checking uname. - # `sysctl` returns the right answer even when running in Rosetta 2. + # NOTE: This is more reliable than checking `uname`. `sysctl` returns + # the right answer even when running in Rosetta 2. def physical_cpu_arm64? sysctl_bool("hw.optional.arm64") end diff --git a/Library/Homebrew/extend/pathname.rb b/Library/Homebrew/extend/pathname.rb index d2c19de115..8b0c072d4c 100644 --- a/Library/Homebrew/extend/pathname.rb +++ b/Library/Homebrew/extend/pathname.rb @@ -126,10 +126,11 @@ class Pathname mkpath - # Use FileUtils.mv over File.rename to handle filesystem boundaries. If src - # is a symlink, and its target is moved first, FileUtils.mv will fail: - # https://bugs.ruby-lang.org/issues/7707 - # In that case, use the system "mv" command. + # Use `FileUtils.mv` over `File.rename` to handle filesystem boundaries. If `src` + # is a symlink and its target is moved first, `FileUtils.mv` will fail + # (https://bugs.ruby-lang.org/issues/7707). + # + # In that case, use the system `mv` command. if src.symlink? raise unless Kernel.system "mv", src.to_s, dst else @@ -178,7 +179,9 @@ class Pathname T.unsafe(self).open("a", **open_args) { |f| f.puts(content) } end - # @note This always overwrites. + # Write to a file atomically. + # + # NOTE: This always overwrites. # # @api public sig { params(content: String).void } @@ -201,6 +204,7 @@ class Pathname # Changing file ownership failed, moving on. nil end + begin # This operation will affect filesystem ACL's chmod(old_stat.mode) diff --git a/Library/Homebrew/fetch.rb b/Library/Homebrew/fetch.rb index 587a17f4ed..9bbd8047e9 100644 --- a/Library/Homebrew/fetch.rb +++ b/Library/Homebrew/fetch.rb @@ -20,7 +20,7 @@ module Homebrew if os.present? return true elsif ENV["HOMEBREW_TEST_GENERIC_OS"].present? - # `:generic` bottles don't exist, and `--os` flag is not specified. + # `:generic` bottles don't exist and `--os` flag is not specified. return false end return true if arch.present? diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index 0d2c5a5508..6175f9abc9 100644 --- a/Library/Homebrew/formula.rb +++ b/Library/Homebrew/formula.rb @@ -48,7 +48,10 @@ require "extend/api_hashable" # @see https://docs.brew.sh/Formula-Cookbook Formula Cookbook # @see https://rubystyle.guide Ruby Style Guide # -# 
class Wget < Formula
+# ### Example
+#
+# ```ruby
+# class Wget < Formula
 #   homepage "https://www.gnu.org/software/wget/"
 #   url "https://ftp.gnu.org/gnu/wget/wget-1.15.tar.gz"
 #   sha256 "52126be8cf1bddd7536886e74c053ad7d0ed2aa89b4b630f76785bac21695fcd"
@@ -57,7 +60,8 @@ require "extend/api_hashable"
 #     system "./configure", "--prefix=#{prefix}"
 #     system "make", "install"
 #   end
-# end
+# end +# ``` class Formula include FileUtils include Utils::Shebang @@ -543,15 +547,20 @@ class Formula # A named {Resource} for the currently active {SoftwareSpec}. # Additional downloads can be defined as {#resource}s. # {Resource#stage} will create a temporary directory and yield to a block. - # 
resource("additional_files").stage { bin.install "my/extra/tool" }
- # @!method resource - delegate resource: :active_spec + # + # ### Example + # + # ```ruby + # resource("additional_files").stage { bin.install "my/extra/tool" } + # ``` + def resource(name) + active_spec.resource(name) + end # An old name for the formula. - # @deprecated Use {#oldnames} instead. sig { returns(T.nilable(String)) } def oldname - odisabled "Formula#oldname", "Formula#oldnames" + odisabled "`Formula#oldname`", "`Formula#oldnames`" @oldname ||= oldnames.first end @@ -589,12 +598,14 @@ class Formula delegate declared_deps: :active_spec # Dependencies provided by macOS for the currently active {SoftwareSpec}. - # @deprecated - delegate uses_from_macos_elements: :active_spec + def uses_from_macos_elements + odisabled "`Formula#uses_from_macos_elements`", "`Formula#declared_deps`" + end # Dependency names provided by macOS for the currently active {SoftwareSpec}. - # @deprecated - delegate uses_from_macos_names: :active_spec + def uses_from_macos_names + odisabled "`Formula#uses_from_macos_names`", "`Formula#declared_deps`" + end # The {Requirement}s for the currently active {SoftwareSpec}. delegate requirements: :active_spec @@ -760,11 +771,19 @@ class Formula # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. # + # ### Examples + # # Need to install into the {.bin} but the makefile doesn't `mkdir -p prefix/bin`? - # 
bin.mkpath
+ # + # ```ruby + # bin.mkpath + # ``` # # No `make install` available? - # 
bin.install "binary1"
+ # + # ```ruby + # bin.install "binary1" + # ``` # # @api public sig { returns(Pathname) } @@ -786,8 +805,13 @@ class Formula # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. # + # ### Example + # # No `make install` available? - # 
include.install "example.h"
+ # + # ```ruby + # include.install "example.h" + # ``` # # @api public sig { returns(Pathname) } @@ -809,8 +833,13 @@ class Formula # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. # + # ### Example + # # No `make install` available? - # 
lib.install "example.dylib"
+ # + # ```ruby + # lib.install "example.dylib" + # ``` # # @api public sig { returns(Pathname) } @@ -823,9 +852,13 @@ class Formula # It is commonly used to install files that we do not wish to be # symlinked into `HOMEBREW_PREFIX` from one of the other directories and # instead manually create symlinks or wrapper scripts into e.g. {#bin}. - # 
libexec.install "foo.jar"
+  #
+  # ### Example
+  #
+  # ```ruby
+  # libexec.install "foo.jar"
   # bin.write_jar_script libexec/"foo.jar", "foo"
-  #
+ # ``` # # @api public sig { returns(Pathname) } @@ -849,8 +882,13 @@ class Formula # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. # + # ### Example + # # No `make install` available? - # 
man1.install "example.1"
+ # + # ```ruby + # man1.install "example.1" + # ``` # # @api public sig { returns(Pathname) } @@ -872,8 +910,13 @@ class Formula # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. # + # ### Example + # # No `make install` available? - # 
man3.install "man.3"
+ # + # ```ruby + # man3.install "man.3" + # ``` # # @api public sig { returns(Pathname) } @@ -946,17 +989,31 @@ class Formula # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. # + # ### Examples + # # Need a custom directory? - # 
(share/"concept").mkpath
+ # + # ```ruby + # (share/"concept").mkpath + # ``` # # Installing something into another custom directory? - # 
(share/"concept2").install "ducks.txt"
+ # + # ```ruby + # (share/"concept2").install "ducks.txt" + # ``` # # Install `./example_code/simple/ones` to `share/demos`: - # 
(share/"demos").install "example_code/simple/ones"
+ # + # ```ruby + # (share/"demos").install "example_code/simple/ones" + # ``` # # Install `./example_code/simple/ones` to `share/demos/examples`: - # 
(share/"demos").install "example_code/simple/ones" => "examples"
+ # + # ```ruby + # (share/"demos").install "example_code/simple/ones" => "examples" + # ``` # # @api public sig { returns(Pathname) } @@ -969,8 +1026,13 @@ class Formula # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. # + # ### Example + # # No `make install` available? - # 
pkgshare.install "examples"
+ # + # ```ruby + # pkgshare.install "examples" + # ``` # # @api public sig { returns(Pathname) } @@ -981,8 +1043,13 @@ class Formula # The directory where Emacs Lisp files should be installed, with the # formula name appended to avoid linking conflicts. # + # ### Example + # # To install an Emacs mode included with a software package: - # 
elisp.install "contrib/emacs/example-mode.el"
+ # + # ```ruby + # elisp.install "contrib/emacs/example-mode.el" + # ``` # # @api public sig { returns(Pathname) } @@ -1134,8 +1201,11 @@ class Formula end # This method can be overridden to provide a plist. - # @see https://www.unix.com/man-page/all/5/plist/ Apple's plist(5) man page - # 
def plist; <<~EOS
+  #
+  # ### Example
+  #
+  # ```ruby
+  # def plist; <<~EOS
   #   
   #   
   #   
@@ -1158,11 +1228,13 @@ class Formula
   #   
   #   
   #   EOS
-  # end
+ # end + # ``` # - # @deprecated Please use {Homebrew::Service} instead. + # @see https://www.unix.com/man-page/all/5/plist/ plist(5) man page def plist # odeprecated: consider removing entirely in 4.3.0 + # odeprecated "`Formula#plist`", "`Homebrew::Service`" nil end @@ -1207,7 +1279,12 @@ class Formula # # This is the preferred way to refer to a formula in plists or from another # formula, as the path is stable even when the software is updated. - # 
args << "--with-readline=#{Formula["readline"].opt_prefix}" if build.with? "readline"
+ # + # ### Example + # + # ```ruby + # args << "--with-readline=#{Formula["readline"].opt_prefix}" if build.with? "readline" + # ``` # # @api public sig { returns(Pathname) } @@ -1353,14 +1430,19 @@ class Formula # Warn the user about any Homebrew-specific issues or quirks for this package. # These should not contain setup instructions that would apply to installation # through a different package manager on a different OS. - # @return [String] - # 
def caveats
+  #
+  # ### Example
+  #
+  # ```ruby
+  # def caveats
   #   <<~EOS
   #     Are optional. Something the user must be warned about?
   #   EOS
-  # end
+ # end + # ``` # - # 
def caveats
+  # ```ruby
+  # def caveats
   #   s = <<~EOS
   #     Print some important notice to the user when `brew info [formula]` is
   #     called or when brewing a formula.
@@ -1368,7 +1450,8 @@ class Formula
   #   EOS
   #   s += "Some issue only on older systems" if MacOS.version < :el_capitan
   #   s
-  # end
+ # end + # ``` sig { overridable.returns(T.nilable(String)) } def caveats nil @@ -1656,6 +1739,7 @@ class Formula delegate pinnable?: :@pin + # !attr[r] pinned? # @api internal delegate pinned?: :@pin @@ -1687,11 +1771,9 @@ class Formula end # @api public - # @!visibility private sig { returns(String) } def to_s = name - # @!visibility private sig { returns(String) } def inspect "#" @@ -1793,11 +1875,14 @@ class Formula # # If `name` is specified as "*", match any shared library of any version. # - # 
shared_library("foo")      #=> foo.dylib
+  # ### Example
+  #
+  # ```ruby
+  # shared_library("foo")      #=> foo.dylib
   # shared_library("foo", 1)   #=> foo.1.dylib
   # shared_library("foo", "*") #=> foo.2.dylib, foo.1.dylib, foo.dylib
   # shared_library("*")        #=> foo.dylib, bar.dylib
-  #
+ # ``` sig { params(name: String, version: T.nilable(T.any(String, Integer))).returns(String) } def shared_library(name, version = nil) return "*.dylib" if name == "*" && (version.blank? || version == "*") @@ -1815,10 +1900,13 @@ class Formula # Optionally specify a `source` or `target` depending on the location # of the file containing the RPATH command and where its target is located. # - # 
rpath #=> "@loader_path/../lib"
+  # ### Example
+  #
+  # ```ruby
+  # rpath #=> "@loader_path/../lib"
   # rpath(target: frameworks) #=> "@loader_path/../Frameworks"
   # rpath(source: libexec/"bin") #=> "@loader_path/../../lib"
-  #
+ # ``` sig { params(source: Pathname, target: Pathname).returns(String) } def rpath(source: bin, target: lib) unless target.to_s.start_with?(HOMEBREW_PREFIX) @@ -1880,68 +1968,96 @@ class Formula end private :extract_macho_slice_from - # Generate shell completions for a formula for bash, zsh, and fish, using the formula's executable. + # Generate shell completions for a formula for `bash`, `zsh` and `fish`, using the formula's executable. # - # @param commands [Pathname, String] the path to the executable and any passed subcommand(s) - # to use for generating the completion scripts. - # @param base_name [String] the base name of the generated completion script. Defaults to the formula name. - # @param shells [Array] the shells to generate completion scripts for. Defaults to `[:bash, :zsh, :fish]`. - # @param shell_parameter_format [String, Symbol] specify how `shells` should each be passed - # to the `executable`. Takes either a String representing a prefix, or one of `[:flag, :arg, :none, :click]`. - # Defaults to plainly passing the shell. + # ### Examples # - # @example Using default values for optional arguments - # generate_completions_from_executable(bin/"foo", "completions") + # Using default values for optional arguments. # - # # translates to - # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "bash") - # (zsh_completion/"_foo").write Utils.safe_popen_read({ "SHELL" => "zsh" }, bin/"foo", "completions", "zsh") - # (fish_completion/"foo.fish").write Utils.safe_popen_read({ "SHELL" => "fish" }, bin/"foo", - # "completions", "fish") + # ```ruby + # generate_completions_from_executable(bin/"foo", "completions") # - # @example Selecting shells and using a different `base_name` - # generate_completions_from_executable(bin/"foo", "completions", shells: [:bash, :zsh], base_name: "bar") + # # translates to + # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "bash") + # (zsh_completion/"_foo").write Utils.safe_popen_read({ "SHELL" => "zsh" }, bin/"foo", "completions", "zsh") + # (fish_completion/"foo.fish").write Utils.safe_popen_read({ "SHELL" => "fish" }, bin/"foo", + # "completions", "fish") + # ``` # - # # translates to - # (bash_completion/"bar").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "bash") - # (zsh_completion/"_bar").write Utils.safe_popen_read({ "SHELL" => "zsh" }, bin/"foo", "completions", "zsh") + # Selecting shells and using a different `base_name`. # - # @example Using predefined `shell_parameter_format :flag` - # generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :flag, shells: [:bash]) + # ```ruby + # generate_completions_from_executable(bin/"foo", "completions", shells: [:bash, :zsh], base_name: "bar") # - # # translates to - # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "--bash") + # # translates to + # (bash_completion/"bar").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "bash") + # (zsh_completion/"_bar").write Utils.safe_popen_read({ "SHELL" => "zsh" }, bin/"foo", "completions", "zsh") + # ``` # - # @example Using predefined `shell_parameter_format :arg` - # generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :arg, shells: [:bash]) + # Using predefined `shell_parameter_format :flag`. # - # # translates to - # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", - # "completions", "--shell=bash") + # ```ruby + # generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :flag, shells: [:bash]) # - # @example Using predefined `shell_parameter_format :none` - # generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :none, shells: [:bash]) + # # translates to + # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions", "--bash") + # ``` # - # # translates to - # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions") + # Using predefined `shell_parameter_format :arg`. # - # @example Using predefined `shell_parameter_format :click` - # generate_completions_from_executable(bin/"foo", shell_parameter_format: :click, shells: [:zsh]) + # ```ruby + # generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :arg, shells: [:bash]) # - # # translates to - # (zsh_completion/"_foo").write Utils.safe_popen_read({ "SHELL" => "zsh", "_FOO_COMPLETE" => "zsh_source" }, - # bin/"foo") + # # translates to + # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", + # "completions", "--shell=bash") + # ``` # - # @example Using custom `shell_parameter_format` - # generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: "--selected-shell=", - # shells: [:bash]) + # Using predefined `shell_parameter_format :none`. # - # # translates to - # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", - # "completions", "--selected-shell=bash") + # ```ruby + # generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: :none, shells: [:bash]) + # + # # translates to + # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", "completions") + # ``` + # + # Using predefined `shell_parameter_format :click`. + # + # ```ruby + # generate_completions_from_executable(bin/"foo", shell_parameter_format: :click, shells: [:zsh]) + # + # # translates to + # (zsh_completion/"_foo").write Utils.safe_popen_read({ "SHELL" => "zsh", "_FOO_COMPLETE" => "zsh_source" }, + # bin/"foo") + # ``` + # + # Using custom `shell_parameter_format`. + # + # ```ruby + # generate_completions_from_executable(bin/"foo", "completions", shell_parameter_format: "--selected-shell=", + # shells: [:bash]) + # + # # translates to + # (bash_completion/"foo").write Utils.safe_popen_read({ "SHELL" => "bash" }, bin/"foo", + # "completions", "--selected-shell=bash") + # ``` + # + # @param commands [Pathname, String] + # the path to the executable and any passed subcommand(s) to use for generating the completion scripts. + # @param base_name [String] + # the base name of the generated completion script. Defaults to the formula name. + # @param shells [Array] + # the shells to generate completion scripts for. Defaults to `[:bash, :zsh, :fish]`. + # @param shell_parameter_format [String, Symbol] + # specify how `shells` should each be passed to the `executable`. Takes either a String representing a + # prefix, or one of `[:flag, :arg, :none, :click]`. Defaults to plainly passing the shell. sig { - params(commands: T.any(Pathname, String), base_name: String, shells: T::Array[Symbol], - shell_parameter_format: T.nilable(T.any(Symbol, String))).void + params( + commands: T.any(Pathname, String), + base_name: String, shells: T::Array[Symbol], + shell_parameter_format: T.nilable(T.any(Symbol, String)) + ).void } def generate_completions_from_executable(*commands, base_name: name, @@ -2129,8 +2245,10 @@ class Formula delegate env: :"self.class" + # !attr[r] conflicts # @api internal - delegate conflicts: :"self.class" + sig { returns(T::Array[FormulaConflict]) } + def conflicts = 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 @@ -2700,10 +2818,15 @@ class Formula # installation instructions. The sources (from {.url}) are downloaded, # hash-checked and then Homebrew changes into a temporary directory where the # archive is unpacked or repository cloned. - # 
def install
+  #
+  # ### Example
+  #
+  # ```ruby
+  # def install
   #   system "./configure", "--prefix=#{prefix}"
   #   system "make", "install"
-  # end
+ # end + # ``` def install; end # Sometimes we have to change a bit before we install. Mostly we @@ -2713,14 +2836,21 @@ class Formula # defined by the formula, as only `HOMEBREW_PREFIX` is available # in the {DATAPatch embedded patch}. # + # ### Examples + # # `inreplace` supports regular expressions: - # 
inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"
+ # + # ```ruby + # inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool" + # ``` # # `inreplace` supports blocks: - # 
inreplace "Makefile" do |s|
+  #
+  # ```ruby
+  # inreplace "Makefile" do |s|
   #   s.gsub! "/usr/local", HOMEBREW_PREFIX.to_s
   # end
-  #
+ # ``` # # @see Utils::Inreplace.inreplace # @api public @@ -2780,26 +2910,43 @@ class Formula # To call out to the system, we use the `system` method and we prefer # you give the args separately as in the line below, otherwise a subshell # has to be opened first. - # 
system "./bootstrap.sh", "--arg1", "--prefix=#{prefix}"
+ # + # ### Examples + # + # ```ruby + # system "./bootstrap.sh", "--arg1", "--prefix=#{prefix}" + # ``` # # For CMake and other build systems we have some necessary defaults in e.g. # {#std_cmake_args}: - # 
system "cmake", ".", *std_cmake_args
+ # + # ```ruby + # system "cmake", ".", *std_cmake_args + # ``` # # If the arguments given to `configure` (or `make` or `cmake`) are depending # on options defined above, we usually make a list first and then # use the `args << if ` to append each: - # 
args = ["--with-option1", "--with-option2"]
-  # args << "--without-gcc" if ENV.compiler == :clang
   #
-  # # Most software still uses `configure` and `make`.
-  # # Check with `./configure --help` for what our options are.
+  # ```ruby
+  # args = ["--with-option1", "--with-option2"]
+  # args << "--without-gcc" if ENV.compiler == :clang
+  # ```
+  #
+  # Most software still uses `configure` and `make`.
+  # Check with `./configure --help` for what our options are.
+  #
+  # ```ruby
   # system "./configure", "--disable-debug", "--disable-dependency-tracking",
   #                       "--disable-silent-rules", "--prefix=#{prefix}",
   #                       *args # our custom arg list (needs `*` to unpack)
+  # ```
   #
-  # # If there is a "make install" available, please use it!
-  # system "make", "install"
+ # If there is a "make install" available, please use it! + # + # ```ruby + # system "make", "install" + # ``` sig { params(cmd: T.any(String, Pathname), args: T.any(String, Integer, Pathname, Symbol)).void } def system(cmd, *args) verbose_using_dots = Homebrew::EnvConfig.verbose_using_dots? @@ -3138,36 +3285,65 @@ class Formula # of the software and Homebrew maintainers. # Shows when running `brew info`. # - # 
desc "Example formula"
+ # ### Example + # + # ```ruby + # desc "Example formula" + # ``` # # @!attribute [w] desc # @api public attr_rw :desc - # @!attribute [w] license # The SPDX ID of the open-source license that the formula uses. # Shows when running `brew info`. + # # Use `:any_of`, `:all_of` or `:with` to describe complex license expressions. # `:any_of` should be used when the user can choose which license to use. # `: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 # licensed under later versions of the same license. - # @see https://docs.brew.sh/License-Guidelines Homebrew License Guidelines - # @see https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/ SPDX license expression guide - # 
license "BSD-2-Clause"
- # 
license "EPL-1.0+"
- # 
license any_of: ["MIT", "GPL-2.0-only"]
- # 
license all_of: ["MIT", "GPL-2.0-only"]
- # 
license "GPL-2.0-only" => { with: "LLVM-exception" }
- # 
license :public_domain
- # 
license any_of: [
+    #
+    # ### Examples
+    #
+    # ```ruby
+    # license "BSD-2-Clause"
+    # ```
+    #
+    # ```ruby
+    # license "EPL-1.0+"
+    # ```
+    #
+    # ```ruby
+    # license any_of: ["MIT", "GPL-2.0-only"]
+    # ```
+    #
+    # ```ruby
+    # license all_of: ["MIT", "GPL-2.0-only"]
+    # ```
+    #
+    # ```ruby
+    # license "GPL-2.0-only" => { with: "LLVM-exception" }
+    # ```
+    #
+    # ```ruby
+    # license :public_domain
+    # ```
+    #
+    # ```ruby
+    # license any_of: [
     #   "MIT",
     #   :public_domain,
     #   all_of: ["0BSD", "Zlib", "Artistic-1.0+"],
     #   "Apache-2.0" => { with: "LLVM-exception" },
-    # ]
+ # ] + # ``` # + # @!attribute [w] license + # @see https://docs.brew.sh/License-Guidelines Homebrew License Guidelines + # @see https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/ SPDX license expression guide # @api public def license(args = nil) if args.nil? @@ -3177,14 +3353,26 @@ class Formula end end - # @!attribute [w] allow_network_access! # The phases for which network access is allowed. By default, network # access is allowed for all phases. Valid phases are `:build`, `:test`, # and `:postinstall`. When no argument is passed, network access will be # allowed for all phases. - # 
allow_network_access!
- # 
allow_network_access! :build
- # 
allow_network_access! [:build, :test]
+ # + # ### Examples + # + # ```ruby + # allow_network_access! + # ``` + # + # ```ruby + # allow_network_access! :build + # ``` + # + # ```ruby + # allow_network_access! [:build, :test] + # ``` + # + # @!attribute [w] allow_network_access! sig { params(phases: T.any(Symbol, T::Array[Symbol])).void } def allow_network_access!(phases = []) phases_array = Array(phases) @@ -3199,14 +3387,26 @@ class Formula end end - # @!attribute [w] deny_network_access! # The phases for which network access is denied. By default, network # access is allowed for all phases. Valid phases are `:build`, `:test`, # and `:postinstall`. When no argument is passed, network access will be # denied for all phases. - # 
deny_network_access!
- # 
deny_network_access! :build
- # 
deny_network_access! [:build, :test]
+ # + # ### Examples + # + # ```ruby + # deny_network_access! + # ``` + # + # ```ruby + # deny_network_access! :build + # ``` + # + # ```ruby + # deny_network_access! [:build, :test] + # ``` + # + # @!attribute [w] deny_network_access! sig { params(phases: T.any(Symbol, T::Array[Symbol])).void } def deny_network_access!(phases = []) phases_array = Array(phases) @@ -3230,35 +3430,43 @@ class Formula env_var.nil? ? @network_access_allowed[phase] : env_var == "allow" end - # @!attribute [w] homepage # The homepage for the software. Used by users to get more information # about the software and Homebrew maintainers as a point of contact for # e.g. submitting patches. # Can be opened with running `brew home`. # - # 
homepage "https://www.example.com"
+ # ### Example + # + # ```ruby + # homepage "https://www.example.com" + # ``` # # @!attribute [w] homepage # @api public attr_rw :homepage - # Whether a livecheck specification is defined or not. - # It returns true when a livecheck block is present in the {Formula} and - # false otherwise, and is used by livecheck. + # Checks whether a `livecheck` specification is defined or not. + # + # It returns `true` when a `livecheck` block is present in the {Formula} + # and `false` otherwise. sig { returns(T::Boolean) } def livecheckable? @livecheckable == true end - # Whether a service specification is defined or not. - # It returns true when a service block is present in the {Formula} and - # false otherwise, and is used by service. + # Checks whether a service specification is defined or not. + # + # It returns `true` when a service block is present in the {Formula} + # and `false` otherwise. sig { returns(T::Boolean) } def service? @service_block.present? end - attr_reader :conflicts, :skip_clean_paths, :link_overwrite_paths, :pour_bottle_only_if + sig { returns(T::Array[FormulaConflict]) } + attr_reader :conflicts + + attr_reader :skip_clean_paths, :link_overwrite_paths, :pour_bottle_only_if # If `pour_bottle?` returns `false` the user-visible reason to display for # why they cannot use the bottle. @@ -3271,7 +3479,11 @@ class Formula # {Formula} to install a new version linked against the new library version. # `0` if unset. # - # 
revision 1
+ # ### Example + # + # ```ruby + # revision 1 + # ``` # # @api public attr_rw :revision @@ -3285,7 +3497,11 @@ class Formula # higher version. # `0` if unset. # - # 
version_scheme 1
+ # ### Example + # + # ```ruby + # version_scheme 1 + # ``` # # @api public attr_rw :version_scheme @@ -3301,7 +3517,6 @@ class Formula end.freeze end - # @!attribute [w] url # The URL used to download the source for the {.stable} version of the formula. # We prefer `https` for security and proxy reasons. # If not inferable, specify the download strategy with `using: ...`. @@ -3311,12 +3526,20 @@ class Formula # - `:nounzip` (without extracting) # - `:post` (download via an HTTP POST) # - # 
url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"
- # 
url "https://some.dont.provide.archives.example.com",
+    # ### Examples
+    #
+    # ```ruby
+    # url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"
+    # ```
+    #
+    # ```ruby
+    # url "https://some.dont.provide.archives.example.com",
     #     using:    :git,
     #     tag:      "1.2.3",
-    #     revision: "db8e4de5b2d6653f66aea53094624468caad15d2"
+ # revision: "db8e4de5b2d6653f66aea53094624468caad15d2" + # ``` # + # @!attribute [w] url # @api public def url(val, specs = {}) stable.url(val, specs) @@ -3327,7 +3550,11 @@ class Formula # The version is autodetected from the URL and/or tag so only needs to be # declared if it cannot be autodetected correctly. # - # 
version "1.2-final"
+ # ### Example + # + # ```ruby + # version "1.2-final" + # ``` # # @api public def version(val = nil) @@ -3341,8 +3568,12 @@ class Formula # is unreliable. If {.url} is really unreliable then we may swap the # {.mirror} and {.url}. # - # 
mirror "https://in.case.the.host.is.down.example.com"
-    # mirror "https://in.case.the.mirror.is.down.example.com
+ # ### Example + # + # ```ruby + # mirror "https://in.case.the.host.is.down.example.com" + # mirror "https://in.case.the.mirror.is.down.example.com + # ``` # # @api public def mirror(val) @@ -3356,14 +3587,17 @@ class Formula # this value you can leave it blank and run `brew fetch --force` and it'll # tell you the currently valid value. # - # 
sha256 "2a2ba417eebaadcb4418ee7b12fe2998f26d6e6f7fda7983412ff66a741ab6f7"
+ # ### Example + # + # ```ruby + # sha256 "2a2ba417eebaadcb4418ee7b12fe2998f26d6e6f7fda7983412ff66a741ab6f7" + # ``` # # @api public def sha256(val) stable.sha256(val) end - # @!attribute [w] bottle # Adds a {.bottle} {SoftwareSpec}. # This provides a pre-built binary package built by the Homebrew maintainers for you. # It will be installed automatically if there is a binary package for your platform @@ -3374,14 +3608,16 @@ class Formula # You can ignore this block entirely if submitting to Homebrew/homebrew-core. # It'll be handled for you by the Brew Test Bot. # - # 
bottle do
+    # ```ruby
+    # bottle do
     #   root_url "https://example.com" # Optional root to calculate bottle URLs.
     #   rebuild 1 # Marks the old bottle as outdated without bumping the version/revision of the formula.
     #   # Optionally specify the HOMEBREW_CELLAR in which the bottles were built.
     #   sha256 cellar: "/brew/Cellar", catalina:    "ef65c759c5097a36323fa9c77756468649e8d1980a3a4e05695c05e39568967c"
     #   sha256 cellar: :any,           mojave:      "28f4090610946a4eb207df102d841de23ced0d06ba31cb79e040d883906dcd4f"
     #   sha256                         high_sierra: "91dd0caca9bd3f38c439d5a7b6f68440c4274945615fae035ff0a369264b8a2f"
-    # end
+ # end + # ``` # # Homebrew maintainers aim to bottle all formulae. # @@ -3409,13 +3645,17 @@ class Formula # 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. # - # 
stable do
+    # ### Example
+    #
+    # ```ruby
+    # stable do
     #   url "https://example.com/foo-1.0.tar.gz"
     #   sha256 "2a2ba417eebaadcb4418ee7b12fe2998f26d6e6f7fda7983412ff66a741ab6f7"
     #
     #   depends_on "libxml2"
     #   depends_on "libffi"
-    # end
+ # end + # ``` # # @api public def stable(&block) @@ -3432,10 +3672,22 @@ class Formula # 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. - # 
head "https://we.prefer.https.over.git.example.com/.git"
- # 
head "https://example.com/.git", branch: "name_of_branch"
+ # + # ### Example + # + # ```ruby + # head "https://we.prefer.https.over.git.example.com/.git" + # ``` + # + # ```ruby + # head "https://example.com/.git", branch: "name_of_branch" + # ``` + # # or (if autodetect fails): - # 
head "https://hg.is.awesome.but.git.has.won.example.com/", using: :hg
+ # + # ```ruby + # head "https://hg.is.awesome.but.git.has.won.example.com/", using: :hg + # ``` def head(val = nil, specs = {}, &block) if block @head.instance_eval(&block) @@ -3449,10 +3701,15 @@ class Formula # Additional downloads can be defined as {resource}s and accessed in the # install method. Resources can also be defined inside a {.stable} or # {.head} block. This mechanism replaces ad-hoc "subformula" classes. - # 
resource "additional_files" do
+    #
+    # ### Example
+    #
+    # ```ruby
+    # resource "additional_files" do
     #   url "https://example.com/additional-stuff.tar.gz"
     #   sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
-    # end
+ # end + # ``` # # @api public def resource(name, klass = Resource, &block) @@ -3461,9 +3718,11 @@ class Formula end end + # Specify a Go resource. + # # @api public def go_resource(name, &block) - # odeprecated "Formula#go_resource", "Go modules" + # odeprecated "`Formula.go_resource`", "Go modules" specs.each { |spec| spec.go_resource(name, &block) } end @@ -3472,37 +3731,62 @@ class Formula # that needs extra handling (often changing some ENV vars or # deciding whether to use the system provided version). # + # ### Examples + # # `:build` means this dependency is only needed during build. - # 
depends_on "cmake" => :build
+ # + # ```ruby + # depends_on "cmake" => :build + # ``` # # `:test` means this dependency is only needed during testing. - # 
depends_on "node" => :test
+ # + # ```ruby + # depends_on "node" => :test + # ``` # # `:recommended` dependencies are built by default. # But a `--without-...` option is generated to opt-out. - # 
depends_on "readline" => :recommended
+ # + # ```ruby + # depends_on "readline" => :recommended + # ``` # # `:optional` dependencies are NOT built by default unless the # auto-generated `--with-...` option is passed. - # 
depends_on "glib" => :optional
+ # + # ```ruby + # depends_on "glib" => :optional + # ``` # # If you need to specify that another formula has to be built with/out # certain options (note, no `--` needed before the option): - # 
depends_on "zeromq" => "with-pgm"
-    # depends_on "qt" => ["with-qtdbus", "developer"] # Multiple options.
+ # + # ```ruby + # depends_on "zeromq" => "with-pgm" + # depends_on "qt" => ["with-qtdbus", "developer"] # Multiple options. + # ``` # # Optional and enforce that "boost" is built using `--with-c++11`. - # 
depends_on "boost" => [:optional, "with-c++11"]
+ # + # ```ruby + # depends_on "boost" => [:optional, "with-c++11"] + # ``` # # If a dependency is only needed in certain cases: - # 
depends_on "sqlite" if MacOS.version >= :catalina
+    #
+    # ```ruby
+    # depends_on "sqlite" if MacOS.version >= :catalina
     # depends_on xcode: :build # If the formula really needs full Xcode to compile.
     # depends_on macos: :mojave # Needs at least macOS Mojave (10.14) to run.
-    #
+ # ``` # # It is possible to only depend on something if # `build.with?` or `build.without? "another_formula"`: - # 
depends_on "postgresql" if build.without? "sqlite"
+ # + # ```ruby + # depends_on "postgresql" if build.without? "sqlite" + # ``` # # @api public def depends_on(dep) @@ -3536,9 +3820,20 @@ class Formula # # - `:universal`: build a universal binary/library (e.g. on newer Intel Macs # this means a combined x86_64/x86 binary/library). - # 
option "with-spam", "The description goes here without a dot at the end"
- # 
option "with-qt", "Text here overwrites what's autogenerated by 'depends_on "qt" => :optional'"
- # 
option :universal
+ # + # ### Examples + # + # ```ruby + # option "with-spam", "The description goes here without a dot at the end" + # ``` + # + # ```ruby + # option "with-qt", "Text here overwrites what's autogenerated by 'depends_on "qt" => :optional'" + # ``` + # + # ```ruby + # option :universal + # ``` # # @api public def option(name, description = "") @@ -3549,7 +3844,12 @@ class Formula # Deprecated options are used to rename options and migrate users who used # them to newer ones. They are mostly used for migrating non-`with` options # (e.g. `enable-debug`) to `with` options (e.g. `with-debug`). - # 
deprecated_option "enable-debug" => "with-debug"
+ # + # ### Example + # + # ```ruby + # deprecated_option "enable-debug" => "with-debug" + # ``` # # @api public def deprecated_option(hash) @@ -3557,44 +3857,66 @@ class Formula end # External patches can be declared using resource-style blocks. - # 
patch do
+    #
+    # ### Examples
+    #
+    # ```ruby
+    # patch do
     #   url "https://example.com/example_patch.diff"
     #   sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
-    # end
+ # end + # ``` # # A strip level of `-p1` is assumed. It can be overridden using a symbol # argument: - # 
patch :p0 do
+    #
+    # ```ruby
+    # patch :p0 do
     #   url "https://example.com/example_patch.diff"
     #   sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
-    # end
+ # end + # ``` # # Patches can be declared in stable and head blocks. This form is # preferred over using conditionals. - # 
stable do
+    #
+    # ```ruby
+    # stable do
     #   patch do
     #     url "https://example.com/example_patch.diff"
     #     sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
     #   end
-    # end
+ # end + # ``` # # Embedded (`__END__`) patches are declared like so: - # 
patch :DATA
-    # patch :p0, :DATA
+ # + # ```ruby + # patch :DATA + # patch :p0, :DATA + # ``` # # Patches can also be embedded by passing a string. This makes it possible # to provide multiple embedded patches while making only some of them # conditional. - # 
patch :p0, "..."
- # @see https://docs.brew.sh/Formula-Cookbook#patches Patches # + # ```ruby + # patch :p0, "..." + # ``` + # + # @see https://docs.brew.sh/Formula-Cookbook#patches Patches # @api public def patch(strip = :p1, src = nil, &block) specs.each { |spec| spec.patch(strip, src, &block) } end # One or more formulae that conflict with this one and why. - # 
conflicts_with "imagemagick", because: "both install `convert` binaries"
+ # + # ### Example + # + # ```ruby + # conflicts_with "imagemagick", because: "both install `convert` binaries" + # ``` # # @api public def conflicts_with(*names) @@ -3605,10 +3927,20 @@ class Formula # Skip cleaning paths in a formula. # # Sometimes the formula {Cleaner cleaner} breaks things. + # + # ### Examples + # # Preserve cleaned paths with: - # 
skip_clean "bin/foo", "lib/bar"
+ # + # ```ruby + # skip_clean "bin/foo", "lib/bar" + # ``` + # # Keep .la files with: - # 
skip_clean :la
+ # + # ```ruby + # skip_clean :la + # ``` # # @api public def skip_clean(*paths) @@ -3619,15 +3951,26 @@ class Formula # Software that will not be symlinked into the `brew --prefix` and will # only live in its Cellar. Other formulae can depend on it and Homebrew - # will add the necessary includes, libraries, and other paths while + # will add the necessary includes, libraries and other paths while # building that other formula. # # Keg-only formulae are not in your PATH and are not seen by compilers # if you build your own software outside of Homebrew. This way, we # don't shadow software provided by macOS. - # 
keg_only :provided_by_macos
- # 
keg_only :versioned_formulae
- # 
keg_only "because I want it so"
+ # + # ### Examples + # + # ```ruby + # keg_only :provided_by_macos + # ``` + # + # ```ruby + # keg_only :versioned_formulae + # ``` + # + # ```ruby + # keg_only "because I want it so" + # ``` # # @api public def keg_only(reason, explanation = "") @@ -3642,13 +3985,19 @@ class Formula end # Marks the {Formula} as failing with a particular compiler so it will fall back to others. + # + # ### Examples + # # For Apple compilers, this should be in the format: - # 
fails_with :clang do
+    #
+    # ```ruby
+    # fails_with :clang do
     #   build 600
     #   cause "multiple configure and compile errors"
-    # end
+ # end + # ``` # - # The block may be omitted, and if present the build may be omitted; + # The block may be omitted and if present, the build may be omitted; # if so, then the compiler will not be allowed for *all* versions. # # `major_version` should be the major release number only, for instance @@ -3659,9 +4008,11 @@ class Formula # For example, if a bug is only triggered on GCC 7.1 but is not # encountered on 7.2: # - # 
fails_with :gcc => '7' do
+    # ```ruby
+    # fails_with :gcc => '7' do
     #   version '7.1'
-    # end
+ # end + # ``` # # @api public def fails_with(compiler, &block) @@ -3684,7 +4035,6 @@ class Formula end # A test is required for new formulae and makes us happy. - # @return [Boolean] # # The block will create, run in and delete a temporary directory. # @@ -3694,42 +4044,53 @@ class Formula # and `foo --version` or `foo --help` are bad tests. # However, a bad test is better than no test at all. # - # @see https://docs.brew.sh/Formula-Cookbook#add-a-test-to-the-formula Tests + # ### Examples # - # 
(testpath/"test.file").write <<~EOS
+    # ```ruby
+    # (testpath/"test.file").write <<~EOS
     #   writing some test file, if you need to
     # EOS
-    # assert_equal "OK", shell_output("test_command test.file").strip
+ # assert_equal "OK", shell_output("test_command test.file").strip + # ``` # # Need complete control over stdin, stdout? - # 
require "open3"
+    #
+    # ```ruby
+    # require "open3"
     # Open3.popen3("#{bin}/example", "argument") do |stdin, stdout, _|
     #   stdin.write("some text")
     #   stdin.close
     #   assert_equal "result", stdout.read
-    # end
+ # end + # ``` # # The test will fail if it returns false, or if an exception is raised. # Failed assertions and failed `system` commands will raise exceptions. # + # @see https://docs.brew.sh/Formula-Cookbook#add-a-test-to-the-formula Tests + # @return [Boolean] # @api public def test(&block) define_method(:test, &block) end - # @!attribute [w] livecheck # {Livecheck} can be used to check for newer versions of the software. # This method evaluates the DSL specified in the livecheck block of the # {Formula} (if it exists) and sets the instance variables of a {Livecheck} # object accordingly. This is used by `brew livecheck` to check for newer # versions of the software. # - # 
livecheck do
+    # ### Example
+    #
+    # ```ruby
+    # livecheck do
     #   skip "Not maintained"
     #   url "https://example.com/foo/releases"
     #   regex /foo-(\d+(?:\.\d+)+)\.tar/
-    # end
+ # end + # ``` # + # @!attribute [w] livecheck # @api public def livecheck(&block) return @livecheck unless block @@ -3738,16 +4099,20 @@ class Formula @livecheck.instance_eval(&block) end - # @!attribute [w] service # Service can be used to define services. # This method evaluates the DSL specified in the service block of the # {Formula} (if it exists) and sets the instance variables of a Service # object accordingly. This is used by `brew install` to generate a service file. # - # 
service do
-    #   run [opt_bin/"foo"]
-    # end
+ # ### Example # + # ```ruby + # service do + # run [opt_bin/"foo"] + # end + # ``` + # + # @!attribute [w] service # @api public def service(&block) return @service_block unless block @@ -3758,18 +4123,26 @@ class Formula # Defines whether the {Formula}'s bottle can be used on the given Homebrew # installation. # - # For example, if the bottle requires the Xcode CLT to be installed a + # ### Examples + # + # If the bottle requires the Xcode CLT to be installed a # {Formula} would declare: - # 
pour_bottle? do
+    #
+    # ```ruby
+    # pour_bottle? do
     #   reason "The bottle needs the Xcode CLT to be installed."
     #   satisfy { MacOS::CLT.installed? }
-    # end
+ # end + # ``` # # If `satisfy` returns `false` then a bottle will not be used and instead # the {Formula} will be built from source and `reason` will be printed. # # Alternatively, a preset reason can be passed as a symbol: - # 
pour_bottle? only_if: :clt_installed
+ # + # ```ruby + # pour_bottle? only_if: :clt_installed + # ``` # # @api public def pour_bottle?(only_if: nil, &block) @@ -3811,11 +4184,19 @@ class Formula # Deprecates a {Formula} (on the given date) so a warning is # shown on each installation. If the date has not yet passed the formula # will not be deprecated. - # 
deprecate! date: "2020-08-27", because: :unmaintained
- # 
deprecate! date: "2020-08-27", because: "has been replaced by foo"
+ # + # ### Examples + # + # ```ruby + # deprecate! date: "2020-08-27", because: :unmaintained + # ``` + # + # ```ruby + # deprecate! date: "2020-08-27", because: "has been replaced by foo" + # ``` + # # @see https://docs.brew.sh/Deprecating-Disabling-and-Removing-Formulae # @see DeprecateDisable::FORMULA_DEPRECATE_DISABLE_REASONS - # # @api public def deprecate!(date:, because:) @deprecation_date = Date.parse(date) @@ -3835,11 +4216,13 @@ class Formula # The date that this {Formula} was or becomes deprecated. # Returns `nil` if no date is specified. + # # @return Date # @see .deprecate! attr_reader :deprecation_date # The reason for deprecation of a {Formula}. + # # @return [nil] if no reason was provided or the formula is not deprecated. # @return [String, Symbol] # @see .deprecate! @@ -3848,11 +4231,19 @@ class Formula # Disables a {Formula} (on the given date) so it cannot be # installed. If the date has not yet passed the formula # will be deprecated instead of disabled. - # 
disable! date: "2020-08-27", because: :does_not_build
- # 
disable! date: "2020-08-27", because: "has been replaced by foo"
+ # + # ### Examples + # + # ```ruby + # disable! date: "2020-08-27", because: :does_not_build + # ``` + # + # ```ruby + # disable! date: "2020-08-27", because: "has been replaced by foo" + # ``` + # # @see https://docs.brew.sh/Deprecating-Disabling-and-Removing-Formulae # @see DeprecateDisable::FORMULA_DEPRECATE_DISABLE_REASONS - # # @api public def disable!(date:, because:) @disable_date = Date.parse(date) @@ -3869,6 +4260,7 @@ class Formula # Whether this {Formula} is disabled (i.e. cannot be installed). # Defaults to false. + # # @see .disable! sig { returns(T::Boolean) } def disabled? @@ -3877,22 +4269,32 @@ class Formula # The date that this {Formula} was or becomes disabled. # Returns `nil` if no date is specified. + # # @return Date # @see .disable! attr_reader :disable_date # The reason this {Formula} is disabled. # Returns `nil` if no reason was provided or the formula is not disabled. + # # @return [String, Symbol] # @see .disable! attr_reader :disable_reason # Permit overwriting certain files while linking. # - # Sometimes we accidentally install files outside prefix. Once we fix that, + # ### Examples + # + # Sometimes we accidentally install files outside the prefix. Once we fix that, # users will get a link conflict error. Overwrite those files with: - # 
link_overwrite "bin/foo", "lib/bar"
- # 
link_overwrite "share/man/man1/baz-*"
+ # + # ```ruby + # link_overwrite "bin/foo", "lib/bar" + # ``` + # + # ```ruby + # link_overwrite "share/man/man1/baz-*" + # ``` def link_overwrite(*paths) paths.flatten! link_overwrite_paths.merge(paths) diff --git a/Library/Homebrew/formula_assertions.rb b/Library/Homebrew/formula_assertions.rb index ad9c7ebcc7..a7d6d0dd77 100644 --- a/Library/Homebrew/formula_assertions.rb +++ b/Library/Homebrew/formula_assertions.rb @@ -16,7 +16,8 @@ module Homebrew @assertions ||= 0 end - # Returns the output of running cmd, and asserts the exit status. + # Returns the output of running cmd and asserts the exit status. + # # @api public def shell_output(cmd, result = 0) ohai cmd @@ -28,8 +29,9 @@ module Homebrew raise end - # Returns the output of running the cmd with the optional input, and + # Returns the output of running the cmd with the optional input and # optionally asserts the exit status. + # # @api public def pipe_output(cmd, input = nil, result = nil) ohai cmd diff --git a/Library/Homebrew/formula_creator.rb b/Library/Homebrew/formula_creator.rb index da833cf4eb..8f362a82f9 100644 --- a/Library/Homebrew/formula_creator.rb +++ b/Library/Homebrew/formula_creator.rb @@ -99,6 +99,8 @@ module Homebrew sig { returns(String) } def template + # FIXME: https://github.com/errata-ai/vale/issues/818 + # <<~ERB # Documentation: https://docs.brew.sh/Formula-Cookbook # https://rubydoc.brew.sh/Formula @@ -183,14 +185,14 @@ module Homebrew ENV.prepend_create_path "PERL5LIB", libexec/"lib/perl5" ENV.prepend_path "PERL5LIB", libexec/"lib" - # Stage additional dependency (Makefile.PL style) + # Stage additional dependency (`Makefile.PL` style). # resource("").stage do # system "perl", "Makefile.PL", "INSTALL_BASE=\#{libexec}" # system "make" # system "make", "install" # end - # Stage additional dependency (Build.PL style) + # Stage additional dependency (`Build.PL` style). # resource("").stage do # system "perl", "Build.PL", "--install_base", libexec # system "./Build" @@ -231,6 +233,7 @@ module Homebrew end end ERB + # end end end diff --git a/Library/Homebrew/formula_support.rb b/Library/Homebrew/formula_support.rb index 838fa97434..77c3a84056 100644 --- a/Library/Homebrew/formula_support.rb +++ b/Library/Homebrew/formula_support.rb @@ -37,7 +37,6 @@ class KegOnlyReason !by_macos? end - # @!visibility private sig { returns(String) } def to_s return @explanation unless @explanation.empty? diff --git a/Library/Homebrew/formula_text_auditor.rb b/Library/Homebrew/formula_text_auditor.rb index 052b811d0b..5600b037bf 100644 --- a/Library/Homebrew/formula_text_auditor.rb +++ b/Library/Homebrew/formula_text_auditor.rb @@ -25,7 +25,6 @@ module Homebrew @text.include? string end - # @!visibility private sig { returns(String) } def to_s @text diff --git a/Library/Homebrew/formulary.rb b/Library/Homebrew/formulary.rb index dada7f3b0b..c479ddacdf 100644 --- a/Library/Homebrew/formulary.rb +++ b/Library/Homebrew/formulary.rb @@ -537,19 +537,19 @@ module Formulary class FormulaLoader include Context - # The formula's name + # The formula's name. sig { returns(String) } attr_reader :name - # The formula's ruby file's path or filename + # The formula file's path. sig { returns(Pathname) } attr_reader :path - # The name used to install the formula + # The name used to install the formula. sig { returns(T.nilable(Pathname)) } attr_reader :alias_path - # The formula's tap (nil if it should be implicitly determined) + # The formula's tap (`nil` if it should be implicitly determined). sig { returns(T.nilable(Tap)) } attr_reader :tap @@ -1019,8 +1019,8 @@ module Formulary # Return a {Formula} instance for the given rack. # # @param spec when nil, will auto resolve the formula's spec. - # @param :alias_path will be used if the formula is found not to be - # installed, and discarded if it is installed because the `alias_path` used + # @param alias_path will be used if the formula is found not to be + # installed and discarded if it is installed because the `alias_path` used # to install the formula will be set instead. sig { params( diff --git a/Library/Homebrew/git_repository.rb b/Library/Homebrew/git_repository.rb index 2f17b2d0f6..5e03a72c1e 100644 --- a/Library/Homebrew/git_repository.rb +++ b/Library/Homebrew/git_repository.rb @@ -106,7 +106,6 @@ class GitRepository popen_git("log", "-1", "--pretty=%B", commit, "--", safe:, err: :out)&.strip end - # @!visibility private sig { returns(String) } def to_s = pathname.to_s diff --git a/Library/Homebrew/github_packages.rb b/Library/Homebrew/github_packages.rb index 68f2f244ad..64aa192cc1 100644 --- a/Library/Homebrew/github_packages.rb +++ b/Library/Homebrew/github_packages.rb @@ -94,12 +94,12 @@ class GitHubPackages end def self.repo_without_prefix(repo) - # remove redundant repo prefix for a shorter name + # Remove redundant repository prefix for a shorter name. repo.delete_prefix("homebrew-") end def self.root_url(org, repo, prefix = URL_PREFIX) - # docker/skopeo insist on lowercase org ("repository name") + # `docker`/`skopeo` insist on lowercase organisation (“repository name”). org = org.downcase "#{prefix}#{org}/#{repo_without_prefix(repo)}" @@ -115,9 +115,9 @@ class GitHubPackages end def self.image_formula_name(formula_name) - # invalid docker name characters - # / makes sense because we already use it to separate repo/formula - # x makes sense because we already use it in Formulary + # Invalid docker name characters: + # - `/` makes sense because we already use it to separate repository/formula. + # - `x` makes sense because we already use it in `Formulary`. formula_name.tr("@", "/") .tr("+", "x") end @@ -231,9 +231,9 @@ class GitHubPackages inspect_args << "--creds=#{user}:#{token}" inspect_result = system_command(skopeo, print_stderr: false, args: inspect_args) - # Order here is important + # Order here is important. if !inspect_result.status.success? && !inspect_result.stderr.match?(/(name|manifest) unknown/) - # We got an error, and it was not about the tag or package being unknown. + # We got an error and it was not about the tag or package being unknown. if warn_on_error opoo "#{image_uri} inspection returned an error, skipping upload!\n#{inspect_result.stderr}" return @@ -241,11 +241,11 @@ class GitHubPackages odie "#{image_uri} inspection returned an error!\n#{inspect_result.stderr}" end elsif keep_old - # If the tag doesn't exist, ignore --keep-old. + # If the tag doesn't exist, ignore `--keep-old`. keep_old = false unless inspect_result.status.success? # Otherwise, do nothing - the tag already existing is expected behaviour for --keep-old. elsif inspect_result.status.success? - # The tag already exists, and we are not passing --keep-old. + # The tag already exists and we are not passing `--keep-old`. if warn_on_error opoo "#{image_uri} already exists, skipping upload!" return diff --git a/Library/Homebrew/keg.rb b/Library/Homebrew/keg.rb index f0b8f79623..e418ce9d48 100644 --- a/Library/Homebrew/keg.rb +++ b/Library/Homebrew/keg.rb @@ -48,7 +48,6 @@ class Keg EOS end - # @!visibility private sig { returns(String) } def to_s s = [] @@ -67,7 +66,6 @@ class Keg # Error for when a directory is not writable. class DirectoryNotWritableError < LinkError - # @!visibility private sig { returns(String) } def to_s <<~EOS @@ -176,11 +174,9 @@ class Keg path.parent end - # @!visibility private sig { returns(String) } def to_s = path.to_s - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}:#{path}>" @@ -556,8 +552,8 @@ class Keg src = dst.resolved_path - # src itself may be a symlink, so check lstat to ensure we are dealing with - # a directory, and not a symlink pointing at a directory (which needs to be + # `src` itself may be a symlink, so check lstat to ensure we are dealing with + # a directory and not a symlink pointing to a directory (which needs to be # treated as a file). In other words, we only want to resolve one symlink. begin diff --git a/Library/Homebrew/language/go.rb b/Library/Homebrew/language/go.rb index f66836ae53..c5344e92b2 100644 --- a/Library/Homebrew/language/go.rb +++ b/Library/Homebrew/language/go.rb @@ -14,7 +14,7 @@ module Language # e.g. `resource "github.com/foo/bar"`. sig { params(resources: T::Array[Resource], target: T.any(String, Pathname)).void } def self.stage_deps(resources, target) - # odeprecated "Language::Go::stage_deps", "Go modules" + # odeprecated "`Language::Go.stage_deps`", "Go modules" if resources.empty? if Homebrew::EnvConfig.developer? odie "Tried to stage empty Language::Go resources array" diff --git a/Library/Homebrew/language/python.rb b/Library/Homebrew/language/python.rb index 71ef9e9bc3..a8006ac5ea 100644 --- a/Library/Homebrew/language/python.rb +++ b/Library/Homebrew/language/python.rb @@ -144,14 +144,14 @@ module Language # Mixin module for {Formula} adding virtualenv support features. module Virtualenv - # Instantiates, creates, and yields a {Virtualenv} object for use from + # Instantiates, creates and yields a {Virtualenv} object for use from # {Formula#install}, which provides helper methods for instantiating and # installing packages into a Python virtualenv. # # @param venv_root [Pathname, String] the path to the root of the virtualenv # (often `libexec/"venv"`) - # @param python [String, Pathname] which interpreter to use (e.g. "python3" - # or "python3.x") + # @param python [String, Pathname] which interpreter to use (e.g. `"python3"` + # or `"python3.x"`) # @param formula [Formula] the active {Formula} # @return [Virtualenv] a {Virtualenv} instance sig { @@ -166,7 +166,7 @@ module Language def virtualenv_create(venv_root, python = "python", formula = T.cast(self, Formula), system_site_packages: true, without_pip: true) # Limit deprecation to 3.12+ for now (or if we can't determine the version). - # Some used this argument for setuptools, which we no longer bundle since 3.12. + # Some used this argument for `setuptools`, which we no longer bundle since 3.12. unless without_pip python_version = Language::Python.major_minor_version(python) if python_version.nil? || python_version.null? || python_version >= "3.12" @@ -198,8 +198,8 @@ module Language # Returns true if a formula option for the specified python is currently # active or if the specified python is required by the formula. Valid - # inputs are "python", "python2", and :python3. Note that - # "with-python", "without-python", "with-python@2", and "without-python@2" + # inputs are `"python"`, `"python2"` and `:python3`. Note that + # `"with-python"`, `"without-python"`, `"with-python@2"` and `"without-python@2"` # formula options are handled correctly even if not associated with any # corresponding depends_on statement. sig { params(python: String).returns(T::Boolean) } @@ -211,7 +211,7 @@ module Language # Helper method for the common case of installing a Python application. # Creates a virtualenv in `libexec`, installs all `resource`s defined - # on the formula, and then installs the formula. An options hash may be + # on the formula and then installs the formula. An options hash may be # passed (e.g. `:using => "python"`) to override the default, guessed # formula preference for python or python@x.y, or to resolve an ambiguous # case where it's not clear whether python or python@x.y should be the diff --git a/Library/Homebrew/lazy_object.rb b/Library/Homebrew/lazy_object.rb index 7f702977ee..364b10f872 100644 --- a/Library/Homebrew/lazy_object.rb +++ b/Library/Homebrew/lazy_object.rb @@ -16,15 +16,20 @@ class LazyObject < Delegator @__delegate__ = @__callable__.call # rubocop:enable Naming/MemoizedInstanceVariableName end + private :__getobj__ def __setobj__(callable) @__callable__ = callable end + private :__setobj__ # Forward to the inner object to make lazy objects type-checkable. + # + # @!visibility private def is_a?(klass) # see https://sorbet.org/docs/faq#how-can-i-fix-type-errors-that-arise-from-super T.bind(self, T.untyped) + __getobj__.is_a?(klass) || super end end diff --git a/Library/Homebrew/livecheck/strategy/extract_plist.rb b/Library/Homebrew/livecheck/strategy/extract_plist.rb index c59d848abd..ba79b24a39 100644 --- a/Library/Homebrew/livecheck/strategy/extract_plist.rb +++ b/Library/Homebrew/livecheck/strategy/extract_plist.rb @@ -39,9 +39,11 @@ module Homebrew ) do extend Forwardable + # @!attribute [r] version # @api public delegate version: :bundle_version + # @!attribute [r] short_version # @api public delegate short_version: :bundle_version end diff --git a/Library/Homebrew/livecheck/strategy/git.rb b/Library/Homebrew/livecheck/strategy/git.rb index 7b5eeee405..ad9ce2526a 100644 --- a/Library/Homebrew/livecheck/strategy/git.rb +++ b/Library/Homebrew/livecheck/strategy/git.rb @@ -13,7 +13,7 @@ module Homebrew # Livecheck has historically prioritized the {Git} strategy over others # and this behavior was continued when the priority setup was created. # This is partly related to Livecheck checking formula URLs in order of - # `head`, `stable`, and then `homepage`. The higher priority here may + # `head`, `stable` and then `homepage`. The higher priority here may # be removed (or altered) in the future if we reevaluate this particular # behavior. # diff --git a/Library/Homebrew/livecheck/strategy/json.rb b/Library/Homebrew/livecheck/strategy/json.rb index b27e990bdf..ce0b8f5cc0 100644 --- a/Library/Homebrew/livecheck/strategy/json.rb +++ b/Library/Homebrew/livecheck/strategy/json.rb @@ -4,7 +4,7 @@ module Homebrew module Livecheck module Strategy - # The {Json} strategy fetches content at a URL, parses it as JSON, and + # The {Json} strategy fetches content at a URL, parses it as JSON and # provides the parsed data to a `strategy` block. If a regex is present # in the `livecheck` block, it should be passed as the second argument to # the `strategy` block. diff --git a/Library/Homebrew/livecheck/strategy/sparkle.rb b/Library/Homebrew/livecheck/strategy/sparkle.rb index c875ec4414..4bae8e669c 100644 --- a/Library/Homebrew/livecheck/strategy/sparkle.rb +++ b/Library/Homebrew/livecheck/strategy/sparkle.rb @@ -54,12 +54,15 @@ module Homebrew ) do extend Forwardable + # @!attribute [r] version # @api public delegate version: :bundle_version + # @!attribute [r] short_version # @api public delegate short_version: :bundle_version + # @!attribute [r] nice_version # @api public delegate nice_version: :bundle_version end diff --git a/Library/Homebrew/livecheck/strategy/xml.rb b/Library/Homebrew/livecheck/strategy/xml.rb index 26c2e874d3..362f373971 100644 --- a/Library/Homebrew/livecheck/strategy/xml.rb +++ b/Library/Homebrew/livecheck/strategy/xml.rb @@ -5,7 +5,7 @@ module Homebrew module Livecheck module Strategy # The {Xml} strategy fetches content at a URL, parses it as XML using - # `REXML`, and provides the `REXML::Document` to a `strategy` block. + # `REXML` and provides the `REXML::Document` to a `strategy` block. # If a regex is present in the `livecheck` block, it should be passed # as the second argument to the `strategy` block. # diff --git a/Library/Homebrew/livecheck/strategy/yaml.rb b/Library/Homebrew/livecheck/strategy/yaml.rb index 60e2290df3..407a8548b7 100644 --- a/Library/Homebrew/livecheck/strategy/yaml.rb +++ b/Library/Homebrew/livecheck/strategy/yaml.rb @@ -4,7 +4,7 @@ module Homebrew module Livecheck module Strategy - # The {Yaml} strategy fetches content at a URL, parses it as YAML, and + # The {Yaml} strategy fetches content at a URL, parses it as YAML and # provides the parsed data to a `strategy` block. If a regex is present # in the `livecheck` block, it should be passed as the second argument to # the `strategy` block. diff --git a/Library/Homebrew/locale.rb b/Library/Homebrew/locale.rb index a4c2d5e695..b6cda9a6e7 100644 --- a/Library/Homebrew/locale.rb +++ b/Library/Homebrew/locale.rb @@ -106,7 +106,6 @@ class Locale locale_groups.find { |locales| locales.any? { |locale| include?(locale) } } end - # @!visibility private sig { returns(String) } def to_s [@language, @script, @region].compact.join("-") diff --git a/Library/Homebrew/macos_version.rb b/Library/Homebrew/macos_version.rb index c03c7d46b7..a8ca466404 100644 --- a/Library/Homebrew/macos_version.rb +++ b/Library/Homebrew/macos_version.rb @@ -132,6 +132,7 @@ class MacOSVersion < Version alias requires_popcnt? requires_nehalem_cpu? # Represents the absence of a version. + # # NOTE: Constructor needs to called with an arbitrary macOS-like version which is then set to `nil`. NULL = MacOSVersion.new("10.0").tap { |v| v.instance_variable_set(:@version, nil) }.freeze end @@ -141,7 +142,7 @@ require "lazy_object" module MacOSVersionErrorCompat def const_missing(name) if name == :MacOSVersionError - odisabled "MacOSVersionError", "MacOSVersion::Error" + odisabled "`MacOSVersionError`", "`MacOSVersion::Error`" return MacOSVersion::Error end @@ -158,7 +159,7 @@ end module MacOSVersions SYMBOLS = LazyObject.new do # rubocop:disable Style/MutableConstant - odisabled "MacOSVersions::SYMBOLS", "MacOSVersion::SYMBOLS" + odisabled "`MacOSVersions::SYMBOLS`", "`MacOSVersion::SYMBOLS`" MacOSVersion::SYMBOLS end end @@ -167,7 +168,7 @@ module OS module Mac # TODO: Replace `::Version` with `Version` when this is removed. Version = LazyObject.new do # rubocop:disable Style/MutableConstant - odisabled "OS::Mac::Version", "MacOSVersion" + odisabled "`OS::Mac::Version`", "`MacOSVersion`" MacOSVersion end end diff --git a/Library/Homebrew/manpages.rb b/Library/Homebrew/manpages.rb index 1d5c3e40c3..6b90a1c186 100644 --- a/Library/Homebrew/manpages.rb +++ b/Library/Homebrew/manpages.rb @@ -142,7 +142,7 @@ module Homebrew sig { returns(String) } def self.global_cask_options_manpage - lines = ["These options are applicable to the `install`, `reinstall`, and `upgrade` " \ + lines = ["These options are applicable to the `install`, `reinstall` and `upgrade` " \ "subcommands with the `--cask` switch.\n"] lines += Homebrew::CLI::Parser.global_cask_options.map do |_, long, kwargs| generate_option_doc(nil, long.chomp("="), kwargs.fetch(:description)) diff --git a/Library/Homebrew/migrator.rb b/Library/Homebrew/migrator.rb index a5465581b3..9da558d5f9 100644 --- a/Library/Homebrew/migrator.rb +++ b/Library/Homebrew/migrator.rb @@ -287,17 +287,18 @@ class Migrator def repin return unless pinned? - # old_pin_record is a relative symlink and when we try to to read it + # `old_pin_record` is a relative symlink and when we try to to read it # from we actually try to find file # /../<...>/../Cellar/name/version. # To repin formula we need to update the link thus that it points to # the right directory. - # NOTE: old_pin_record.realpath.sub(oldname, newname) is unacceptable - # here, because it resolves every symlink for old_pin_record and then + # + # NOTE: `old_pin_record.realpath.sub(oldname, newname)` is unacceptable + # here, because it resolves every symlink for `old_pin_record` and then # substitutes oldname with newname. It breaks things like - # Pathname#make_relative_symlink, where Pathname#relative_path_from - # is used to find relative path from source to destination parent and - # it assumes no symlinks. + # `Pathname#make_relative_symlink`, where `Pathname#relative_path_from` + # is used to find the relative path from source to destination parent + # and it assumes no symlinks. src_oldname = (old_pin_record.dirname/old_pin_link_record).expand_path new_pin_record.make_relative_symlink(src_oldname.sub(oldname, newname)) old_pin_record.delete diff --git a/Library/Homebrew/mktemp.rb b/Library/Homebrew/mktemp.rb index da9e487ba1..2d03ec6fca 100644 --- a/Library/Homebrew/mktemp.rb +++ b/Library/Homebrew/mktemp.rb @@ -1,7 +1,7 @@ # typed: true # frozen_string_literal: true -# Performs {Formula#mktemp}'s functionality, and tracks the results. +# Performs {Formula#mktemp}'s functionality and tracks the results. # Each instance is only intended to be used once. class Mktemp include FileUtils @@ -38,7 +38,6 @@ class Mktemp @quiet = true end - # @!visibility private sig { returns(String) } def to_s "[Mktemp: #{tmpdir} retain=#{@retain} quiet=#{@quiet}]" diff --git a/Library/Homebrew/options.rb b/Library/Homebrew/options.rb index 572d615358..6d7d0dfd9d 100644 --- a/Library/Homebrew/options.rb +++ b/Library/Homebrew/options.rb @@ -11,7 +11,6 @@ class Option @description = description end - # @!visibility private sig { returns(String) } def to_s = flag @@ -30,7 +29,6 @@ class Option name.hash end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: #{flag.inspect}>" @@ -134,13 +132,11 @@ class Options alias to_ary to_a - # @!visibility private sig { returns(String) } def to_s @options.map(&:to_s).join(" ") end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: #{to_a.inspect}>" diff --git a/Library/Homebrew/os/mac/sdk.rb b/Library/Homebrew/os/mac/sdk.rb index 59471c744d..efea57282a 100644 --- a/Library/Homebrew/os/mac/sdk.rb +++ b/Library/Homebrew/os/mac/sdk.rb @@ -173,8 +173,8 @@ module OS # using that. # As of Xcode 10, the Unix-style headers are installed via a # separate package, so we can't rely on their being present. - # This will only look up SDKs on Xcode 10 or newer, and still - # return nil SDKs for Xcode 9 and older. + # This will only look up SDKs on Xcode 10 or newer and still + # return `nil` SDKs for Xcode 9 and older. sig { override.returns(String) } def sdk_prefix @sdk_prefix ||= if CLT.provides_sdk? diff --git a/Library/Homebrew/patch.rb b/Library/Homebrew/patch.rb index 5187661442..2f7cceae95 100644 --- a/Library/Homebrew/patch.rb +++ b/Library/Homebrew/patch.rb @@ -51,7 +51,6 @@ class EmbeddedPatch Utils.safe_popen_write("patch", *args) { |p| p.write(data) } end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: #{strip.inspect}>" @@ -151,7 +150,6 @@ class ExternalPatch raise BuildError.new(f, cmd, args, ENV.to_hash) end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: #{strip.inspect} #{url.inspect}>" diff --git a/Library/Homebrew/pkg_version.rb b/Library/Homebrew/pkg_version.rb index c72505cc63..b29a52de81 100644 --- a/Library/Homebrew/pkg_version.rb +++ b/Library/Homebrew/pkg_version.rb @@ -39,7 +39,6 @@ class PkgVersion end end - # @!visibility private sig { returns(String) } def to_s = to_str diff --git a/Library/Homebrew/requirement.rb b/Library/Homebrew/requirement.rb index 038595fd9c..d8df3552e9 100644 --- a/Library/Homebrew/requirement.rb +++ b/Library/Homebrew/requirement.rb @@ -140,7 +140,6 @@ class Requirement [self.class, name, tags].hash end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: #{tags.inspect}>" diff --git a/Library/Homebrew/requirements/arch_requirement.rb b/Library/Homebrew/requirements/arch_requirement.rb index 0f900a162e..9db2d151ca 100644 --- a/Library/Homebrew/requirements/arch_requirement.rb +++ b/Library/Homebrew/requirements/arch_requirement.rb @@ -27,7 +27,6 @@ class ArchRequirement < Requirement "The #{@arch} architecture is required for this software." end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: arch=#{@arch.to_s.inspect} #{tags.inspect}>" diff --git a/Library/Homebrew/requirements/macos_requirement.rb b/Library/Homebrew/requirements/macos_requirement.rb index ac4f9b1b9e..0e7e0cd06e 100644 --- a/Library/Homebrew/requirements/macos_requirement.rb +++ b/Library/Homebrew/requirements/macos_requirement.rb @@ -96,7 +96,6 @@ class MacOSRequirement < Requirement [super, comparator, version].hash end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: version#{@comparator}#{@version.to_s.inspect} #{tags.inspect}>" diff --git a/Library/Homebrew/requirements/xcode_requirement.rb b/Library/Homebrew/requirements/xcode_requirement.rb index 8d4d8c2d1a..0494fd5fae 100644 --- a/Library/Homebrew/requirements/xcode_requirement.rb +++ b/Library/Homebrew/requirements/xcode_requirement.rb @@ -48,7 +48,6 @@ class XcodeRequirement < Requirement end end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}: version>=#{@version.inspect} #{tags.inspect}>" diff --git a/Library/Homebrew/resource.rb b/Library/Homebrew/resource.rb index 910bc44e11..7a7517184e 100644 --- a/Library/Homebrew/resource.rb +++ b/Library/Homebrew/resource.rb @@ -146,17 +146,22 @@ class Resource < Downloadable super(verify_download_integrity:) end - # @!attribute [w] livecheck # {Livecheck} can be used to check for newer versions of the software. # This method evaluates the DSL specified in the livecheck block of the # {Resource} (if it exists) and sets the instance variables of a {Livecheck} # object accordingly. This is used by `brew livecheck` to check for newer # versions of the software. # - # 
livecheck do
+  # ### Example
+  #
+  # ```ruby
+  # livecheck do
   #   url "https://example.com/foo/releases"
   #   regex /foo-(\d+(?:\.\d+)+)\.tar/
-  # end
+ # end + # ``` + # + # @!attribute [w] livecheck def livecheck(&block) return @livecheck unless block @@ -165,8 +170,8 @@ class Resource < Downloadable end # Whether a livecheck specification is defined or not. - # It returns true when a livecheck block is present in the {Resource} and - # false otherwise, and is used by livecheck. + # It returns true when a `livecheck` block is present in the {Resource} and + # false otherwise and is used by livecheck. def livecheckable? @livecheckable == true end @@ -302,7 +307,6 @@ class ResourceStageContext @staging = staging end - # @!visibility private sig { returns(String) } def to_s "<#{self.class}: resource=#{resource} staging=#{staging}>" diff --git a/Library/Homebrew/rubocops/blank.rb b/Library/Homebrew/rubocops/blank.rb index e6a22cb890..b32f1f9412 100644 --- a/Library/Homebrew/rubocops/blank.rb +++ b/Library/Homebrew/rubocops/blank.rb @@ -4,27 +4,26 @@ module RuboCop module Cop module Homebrew - # Checks for code that can be written with simpler conditionals - # using `Object#blank?`. + # Checks for code that can be simplified using `Object#blank?`. # - # @note - # This cop is unsafe autocorrection, because `' '.empty?` returns false, - # but `' '.blank?` returns true. Therefore, autocorrection is not compatible - # if the receiver is a non-empty blank string, tab, or newline meta characters. + # NOTE: Auto-correction for this cop is unsafe because `' '.empty?` returns `false`, + # but `' '.blank?` returns `true`. Therefore, auto-correction is not compatible + # if the receiver is a non-empty blank string. # - # @example - # # Converts usages of `nil? || empty?` to `blank?` + # ### Example # - # # bad - # foo.nil? || foo.empty? - # foo == nil || foo.empty? + # ```ruby + # # bad + # foo.nil? || foo.empty? + # foo == nil || foo.empty? # - # # good - # foo.blank? + # # good + # foo.blank? + # ``` class Blank < Base extend AutoCorrector - MSG_NIL_OR_EMPTY = "Use `%s` instead of `%s`." + MSG = "Use `%s` instead of `%s`." # `(send nil $_)` is not actually a valid match for an offense. Nodes # that have a single method call on the left hand side @@ -49,7 +48,7 @@ module RuboCop nil_or_empty?(node) do |var1, var2| return if var1 != var2 - message = format(MSG_NIL_OR_EMPTY, prefer: replacement(var1), current: node.source) + message = format(MSG, prefer: replacement(var1), current: node.source) add_offense(node, message:) do |corrector| autocorrect(corrector, node) end diff --git a/Library/Homebrew/rubocops/cask/array_alphabetization.rb b/Library/Homebrew/rubocops/cask/array_alphabetization.rb index 8e3e93b22d..ddbd872e4a 100644 --- a/Library/Homebrew/rubocops/cask/array_alphabetization.rb +++ b/Library/Homebrew/rubocops/cask/array_alphabetization.rb @@ -44,7 +44,7 @@ module RuboCop end # Separate the lines into those that should be sorted and those that should not - # ie. skip the opening and closing brackets of the array + # i.e. skip the opening and closing brackets of the array. to_sort, to_keep = combined_source.partition { |line| !line.include?("[") && !line.include?("]") } # Sort the lines that should be sorted diff --git a/Library/Homebrew/rubocops/cask/on_system_conditionals.rb b/Library/Homebrew/rubocops/cask/on_system_conditionals.rb index 3039ea9304..d6a267e4ba 100644 --- a/Library/Homebrew/rubocops/cask/on_system_conditionals.rb +++ b/Library/Homebrew/rubocops/cask/on_system_conditionals.rb @@ -9,20 +9,23 @@ module RuboCop module Cask # This cop makes sure that OS conditionals are consistent. # - # @example - # # bad - # cask 'foo' do - # if MacOS.version == :high_sierra - # sha256 "..." - # end - # end + # ### Example # - # # good - # cask 'foo' do - # on_high_sierra do - # sha256 "..." - # end + # ```ruby + # # bad + # cask 'foo' do + # if MacOS.version == :high_sierra + # sha256 "..." # end + # end + # + # # good + # cask 'foo' do + # on_high_sierra do + # sha256 "..." + # end + # end + # ``` class OnSystemConditionals < Base extend Forwardable extend AutoCorrector diff --git a/Library/Homebrew/rubocops/cask/url.rb b/Library/Homebrew/rubocops/cask/url.rb index 49f859310b..e8bc4f08c8 100644 --- a/Library/Homebrew/rubocops/cask/url.rb +++ b/Library/Homebrew/rubocops/cask/url.rb @@ -6,16 +6,17 @@ module RuboCop module Cask # This cop checks that a cask's `url` stanza is formatted correctly. # - # @example - # # bad - # url "https://example.com/download/foo.dmg", - # verified: "https://example.com/download" + # ### Example # + # ```ruby + # # bad + # url "https://example.com/download/foo.dmg", + # verified: "https://example.com/download" # - # # good - # url "https://example.com/download/foo.dmg", - # verified: "example.com/download/" - # + # # good + # url "https://example.com/download/foo.dmg", + # verified: "example.com/download/" + # ``` class Url < Base extend AutoCorrector extend Forwardable @@ -43,7 +44,7 @@ module RuboCop # Skip if the URL and the verified value are the same. next if value_node.source == url_stanza.source.gsub(%r{^"https?://}, "\"") - # Skip if the URL has two path components, eg: `https://github.com/google/fonts.git`. + # Skip if the URL has two path components, e.g. `https://github.com/google/fonts.git`. next if url_stanza.source.gsub(%r{^"https?://}, "\"").count("/") == 2 # Skip if the verified value ends with a slash. next if value_node.str_content.end_with?("/") diff --git a/Library/Homebrew/rubocops/cask/variables.rb b/Library/Homebrew/rubocops/cask/variables.rb index 95352ddd22..8a641291f7 100644 --- a/Library/Homebrew/rubocops/cask/variables.rb +++ b/Library/Homebrew/rubocops/cask/variables.rb @@ -8,16 +8,19 @@ module RuboCop module Cask # This cop audits variables in casks. # - # @example - # # bad - # cask do - # arch = Hardware::CPU.intel? ? "darwin" : "darwin-arm64" - # end + # ### Example # - # # good - # cask 'foo' do - # arch arm: "darwin-arm64", intel: "darwin" - # end + # ```ruby + # # bad + # cask do + # arch = Hardware::CPU.intel? ? "darwin" : "darwin-arm64" + # end + # + # # good + # cask 'foo' do + # arch arm: "darwin-arm64", intel: "darwin" + # end + # ``` class Variables < Base extend Forwardable extend AutoCorrector diff --git a/Library/Homebrew/rubocops/caveats.rb b/Library/Homebrew/rubocops/caveats.rb index 048ddd5bf9..b1a6926606 100644 --- a/Library/Homebrew/rubocops/caveats.rb +++ b/Library/Homebrew/rubocops/caveats.rb @@ -6,27 +6,30 @@ require "rubocops/extend/formula_cop" module RuboCop module Cop module FormulaAudit - # This cop makes sure that caveats don't recommend unsupported or unsafe operations. + # This cop ensures that caveats don't recommend unsupported or unsafe operations. # - # @example - # # bad - # def caveats - # <<~EOS - # Use `setuid` to allow running the exeutable by non-root users. - # EOS - # end + # ### Example # - # # good - # def caveats - # <<~EOS - # Use `sudo` to run the executable. - # EOS - # end + # ```ruby + # # bad + # def caveats + # <<~EOS + # Use `setuid` to allow running the exeutable by non-root users. + # EOS + # end + # + # # good + # def caveats + # <<~EOS + # Use `sudo` to run the executable. + # EOS + # end + # ``` class Caveats < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, _body_node) caveats_strings.each do |n| if regex_match_group(n, /\bsetuid\b/i) - problem "Don't recommend setuid in the caveats, suggest sudo instead." + problem "Don't recommend `setuid` in the caveats, suggest `sudo` instead." end problem "Don't use ANSI escape codes in the caveats." if regex_match_group(n, /\e/) diff --git a/Library/Homebrew/rubocops/compact_blank.rb b/Library/Homebrew/rubocops/compact_blank.rb index 0bdf44159e..9603abb675 100644 --- a/Library/Homebrew/rubocops/compact_blank.rb +++ b/Library/Homebrew/rubocops/compact_blank.rb @@ -6,43 +6,46 @@ module RuboCop module Homebrew # Checks if collection can be blank-compacted with `compact_blank`. # - # @note - # It is unsafe by default because false positives may occur in the - # blank check of block arguments to the receiver object. + # NOTE: It is unsafe by default because false positives may occur in the + # blank check of block arguments to the receiver object. # - # For example, `[[1, 2], [3, nil]].reject { |first, second| second.blank? }` and - # `[[1, 2], [3, nil]].compact_blank` are not compatible. The same is true for `blank?`. - # This will work fine when the receiver is a hash object. + # For example, `[[1, 2], [3, nil]].reject { |first, second| second.blank? }` and + # `[[1, 2], [3, nil]].compact_blank` are not compatible. The same is true for `blank?`. + # This will work fine when the receiver is a hash object. # - # And `compact_blank!` has different implementations for `Array`, `Hash`, and - # `ActionController::Parameters`. - # `Array#compact_blank!`, `Hash#compact_blank!` are equivalent to `delete_if(&:blank?)`. - # `ActionController::Parameters#compact_blank!` is equivalent to `reject!(&:blank?)`. - # If the cop makes a mistake, autocorrected code may get unexpected behavior. + # And `compact_blank!` has different implementations for `Array`, `Hash` and + # `ActionController::Parameters`. + # `Array#compact_blank!`, `Hash#compact_blank!` are equivalent to `delete_if(&:blank?)`. + # `ActionController::Parameters#compact_blank!` is equivalent to `reject!(&:blank?)`. + # If the cop makes a mistake, autocorrected code may get unexpected behavior. # - # @example + # ### Examples # - # # bad - # collection.reject(&:blank?) - # collection.reject { |_k, v| v.blank? } + # ```ruby + # # bad + # collection.reject(&:blank?) + # collection.reject { |_k, v| v.blank? } # - # # good - # collection.compact_blank + # # good + # collection.compact_blank + # ``` # - # # bad - # collection.delete_if(&:blank?) # Same behavior as `Array#compact_blank!` and `Hash#compact_blank!` - # collection.delete_if { |_, v| v.blank? } # Same behavior as `Array#compact_blank!` and `Hash#compact_blank!` - # collection.reject!(&:blank?) # Same behavior as `ActionController::Parameters#compact_blank!` - # collection.reject! { |_k, v| v.blank? } # Same behavior as `ActionController::Parameters#compact_blank!` - # - # # good - # collection.compact_blank! + # ```ruby + # # bad + # collection.delete_if(&:blank?) # Same behavior as `Array#compact_blank!` and `Hash#compact_blank!` + # collection.delete_if { |_, v| v.blank? } # Same behavior as `Array#compact_blank!` and `Hash#compact_blank!` + # collection.reject!(&:blank?) # Same behavior as `ActionController::Parameters#compact_blank!` + # collection.reject! { |_k, v| v.blank? } # Same behavior as `ActionController::Parameters#compact_blank!` # + # # good + # collection.compact_blank! + # ``` class CompactBlank < Base include RangeHelp extend AutoCorrector MSG = "Use `%s` instead." + RESTRICT_ON_SEND = [:reject, :delete_if, :reject!].freeze def_node_matcher :reject_with_block?, <<~PATTERN diff --git a/Library/Homebrew/rubocops/homepage.rb b/Library/Homebrew/rubocops/homepage.rb index ccf498c146..c29ca23883 100644 --- a/Library/Homebrew/rubocops/homepage.rb +++ b/Library/Homebrew/rubocops/homepage.rb @@ -69,8 +69,8 @@ module RuboCop # # Compact the above into this list as we're able to remove detailed notations, etc over time. when - # Check for http:// GitHub homepage URLs, https:// is preferred. - # Note: only check homepages that are repo pages, not *.github.com hosts + # Check for `http://` GitHub homepage URLs, `https://` is preferred. + # NOTE: Only check homepages that are repository pages, not `*.github.com` hosts. %r{^http://github\.com/}, %r{^http://[^/]*\.github\.io/}, diff --git a/Library/Homebrew/rubocops/io_read.rb b/Library/Homebrew/rubocops/io_read.rb index 0b58afea01..46ad7e1320 100644 --- a/Library/Homebrew/rubocops/io_read.rb +++ b/Library/Homebrew/rubocops/io_read.rb @@ -4,9 +4,10 @@ module RuboCop module Cop module Homebrew - # This cop restricts usage of IO.read functions for security reasons. + # This cop restricts usage of `IO.read` functions for security reasons. class IORead < Base MSG = "The use of `IO.%s` is a security risk." + RESTRICT_ON_SEND = [:read, :readlines].freeze def on_send(node) diff --git a/Library/Homebrew/rubocops/negate_include.rb b/Library/Homebrew/rubocops/negate_include.rb index ccfec44c7c..ad164c2287 100644 --- a/Library/Homebrew/rubocops/negate_include.rb +++ b/Library/Homebrew/rubocops/negate_include.rb @@ -7,23 +7,25 @@ module RuboCop # Enforces the use of `collection.exclude?(obj)` # over `!collection.include?(obj)`. # - # @note - # This cop is unsafe because false positive will occur for - # receiver objects that do not have an `exclude?` method. (e.g. `IPAddr`) + # NOTE: This cop is unsafe because false positives will occur for + # receiver objects that do not have an `#exclude?` method (e.g. `IPAddr`). # - # @example - # # bad - # !array.include?(2) - # !hash.include?(:key) + # ### Example # - # # good - # array.exclude?(2) - # hash.exclude?(:key) + # ```ruby + # # bad + # !array.include?(2) + # !hash.include?(:key) # + # # good + # array.exclude?(2) + # hash.exclude?(:key) + # ``` class NegateInclude < Base extend AutoCorrector MSG = "Use `.exclude?` and remove the negation part." + RESTRICT_ON_SEND = [:!].freeze def_node_matcher :negate_include_call?, <<~PATTERN diff --git a/Library/Homebrew/rubocops/presence.rb b/Library/Homebrew/rubocops/presence.rb index 97fb8497f9..eddb3afe84 100644 --- a/Library/Homebrew/rubocops/presence.rb +++ b/Library/Homebrew/rubocops/presence.rb @@ -7,37 +7,41 @@ module RuboCop # Checks code that can be written more easily using # `Object#presence` defined by Active Support. # - # @example - # # bad - # a.present? ? a : nil + # ### Examples # - # # bad - # !a.present? ? nil : a + # ```ruby + # # bad + # a.present? ? a : nil # - # # bad - # a.blank? ? nil : a + # # bad + # !a.present? ? nil : a # - # # bad - # !a.blank? ? a : nil + # # bad + # a.blank? ? nil : a # - # # good - # a.presence + # # bad + # !a.blank? ? a : nil # - # @example - # # bad - # a.present? ? a : b + # # good + # a.presence + # ``` # - # # bad - # !a.present? ? b : a + # ```ruby + # # bad + # a.present? ? a : b # - # # bad - # a.blank? ? b : a + # # bad + # !a.present? ? b : a # - # # bad - # !a.blank? ? a : b + # # bad + # a.blank? ? b : a # - # # good - # a.presence || b + # # bad + # !a.blank? ? a : b + # + # # good + # a.presence || b + # ``` class Presence < Base include RangeHelp extend AutoCorrector diff --git a/Library/Homebrew/rubocops/present.rb b/Library/Homebrew/rubocops/present.rb index fb83c69192..80f8ad18cc 100644 --- a/Library/Homebrew/rubocops/present.rb +++ b/Library/Homebrew/rubocops/present.rb @@ -4,24 +4,24 @@ module RuboCop module Cop module Homebrew - # Checks for code that can be written with simpler conditionals - # using `Object#present?`. + # Checks for code that can be simplified using `Object#present?`. # - # @example - # # Converts usages of `!nil? && !empty?` to `present?` + # ### Example # - # # bad - # !foo.nil? && !foo.empty? + # ```ruby + # # bad + # !foo.nil? && !foo.empty? # - # # bad - # foo != nil && !foo.empty? + # # bad + # foo != nil && !foo.empty? # - # # good - # foo.present? + # # good + # foo.present? + # ``` class Present < Base extend AutoCorrector - MSG_EXISTS_AND_NOT_EMPTY = "Use `%s` instead of `%s`." + MSG = "Use `%s` instead of `%s`." def_node_matcher :exists_and_not_empty?, <<~PATTERN (and @@ -41,7 +41,7 @@ module RuboCop exists_and_not_empty?(node) do |var1, var2| return if var1 != var2 - message = format(MSG_EXISTS_AND_NOT_EMPTY, prefer: replacement(var1), current: node.source) + message = format(MSG, prefer: replacement(var1), current: node.source) add_offense(node, message:) do |corrector| autocorrect(corrector, node) @@ -53,7 +53,7 @@ module RuboCop exists_and_not_empty?(node) do |var1, var2| return if var1 != var2 - add_offense(node, message: MSG_EXISTS_AND_NOT_EMPTY) do |corrector| + add_offense(node, message: MSG) do |corrector| autocorrect(corrector, node) end end diff --git a/Library/Homebrew/rubocops/safe_navigation_with_blank.rb b/Library/Homebrew/rubocops/safe_navigation_with_blank.rb index 4e104d2d5e..8862da6d58 100644 --- a/Library/Homebrew/rubocops/safe_navigation_with_blank.rb +++ b/Library/Homebrew/rubocops/safe_navigation_with_blank.rb @@ -7,28 +7,26 @@ module RuboCop # Checks to make sure safe navigation isn't used with `blank?` in # a conditional. # - # @note - # While the safe navigation operator is generally a good idea, when - # checking `foo&.blank?` in a conditional, `foo` being `nil` will actually - # do the opposite of what the author intends. + # NOTE: While the safe navigation operator is generally a good idea, when + # checking `foo&.blank?` in a conditional, `foo` being `nil` will actually + # do the opposite of what the author intends: # - # For example: + # ```ruby + # foo&.blank? #=> nil + # foo.blank? #=> true + # ``` # - # [source,ruby] - # ---- - # foo&.blank? #=> nil - # foo.blank? #=> true - # ---- + # ### Example # - # @example - # # bad - # do_something if foo&.blank? - # do_something unless foo&.blank? - # - # # good - # do_something if foo.blank? - # do_something unless foo.blank? + # ```ruby + # # bad + # do_something if foo&.blank? + # do_something unless foo&.blank? # + # # good + # do_something if foo.blank? + # do_something unless foo.blank? + # ``` class SafeNavigationWithBlank < Base extend AutoCorrector diff --git a/Library/Homebrew/rubocops/service.rb b/Library/Homebrew/rubocops/service.rb index a141e6fc74..e63a0a9917 100644 --- a/Library/Homebrew/rubocops/service.rb +++ b/Library/Homebrew/rubocops/service.rb @@ -30,7 +30,7 @@ module RuboCop method_calls.delete(:service) # NOTE: Solving the first problem here might solve the second one too - # so we don't show both of them at the same time. + # so we don't show both of them at the same time. if !method_calls.keys.intersect?(REQUIRED_METHOD_CALLS) offending_node(service_node) problem "Service blocks require `run` or `name` to be defined." diff --git a/Library/Homebrew/rubocops/shared/helper_functions.rb b/Library/Homebrew/rubocops/shared/helper_functions.rb index 4a62e02b2f..7e6d9f6601 100644 --- a/Library/Homebrew/rubocops/shared/helper_functions.rb +++ b/Library/Homebrew/rubocops/shared/helper_functions.rb @@ -174,10 +174,19 @@ module RuboCop # Matches a method with a receiver. Yields to a block with matching method node. # - # @example to match `Formula.factory(name)` - # find_instance_method_call(node, "Formula", :factory) - # @example to match `build.head?` - # find_instance_method_call(node, :build, :head?) + # ### Examples + # + # Match `Formula.factory(name)`. + # + # ```ruby + # find_instance_method_call(node, "Formula", :factory) + # ``` + # + # Match `build.head?`. + # + # ```ruby + # find_instance_method_call(node, :build, :head?) + # ``` def find_instance_method_call(node, instance, method_name) methods = find_every_method_call_by_name(node, method_name) methods.each do |method| @@ -194,8 +203,13 @@ module RuboCop # Matches receiver part of method. Yields to a block with parent node of receiver. # - # @example to match `ARGV.()` - # find_instance_call(node, "ARGV") + # ### Example + # + # Match `ARGV.()`. + # + # ```ruby + # find_instance_call(node, "ARGV") + # ``` def find_instance_call(node, name) node.each_descendant(:send) do |method_node| next if method_node.receiver.nil? diff --git a/Library/Homebrew/rubocops/shell_commands.rb b/Library/Homebrew/rubocops/shell_commands.rb index 537c1be798..4d0dac7f7f 100644 --- a/Library/Homebrew/rubocops/shell_commands.rb +++ b/Library/Homebrew/rubocops/shell_commands.rb @@ -40,9 +40,11 @@ module RuboCop until while ].freeze + private_constant :SHELL_BUILTINS # https://github.com/ruby/ruby/blob/v2_6_3/process.c#L2495 SHELL_METACHARACTERS = %W[* ? { } [ ] < > ( ) ~ & | \\ $ ; ' ` " \n #].freeze + private_constant :SHELL_METACHARACTERS # This cop makes sure that shell command arguments are separated. class ShellCommands < Base @@ -60,6 +62,8 @@ module RuboCop [:Utils, :popen_write], [:Utils, :safe_popen_write], ].freeze + private_constant :TARGET_METHODS + RESTRICT_ON_SEND = TARGET_METHODS.map(&:second).uniq.freeze def on_send(node) diff --git a/Library/Homebrew/rubocops/urls.rb b/Library/Homebrew/rubocops/urls.rb index 4e388166c2..f330387a41 100644 --- a/Library/Homebrew/rubocops/urls.rb +++ b/Library/Homebrew/rubocops/urls.rb @@ -127,7 +127,7 @@ module RuboCop # SourceForge url patterns sourceforge_patterns = %r{^https?://.*\b(sourceforge|sf)\.(com|net)} audit_urls(urls, sourceforge_patterns) do |_, url| - # Skip if the URL looks like a SVN repo + # Skip if the URL looks like a SVN repository. next if url.include? "/svnroot/" next if url.include? "svn.sourceforge" next if url.include? "/p/" @@ -183,19 +183,19 @@ module RuboCop problem "Please use https:// for #{url}" end - # Check for git:// GitHub repo URLs, https:// is preferred. + # Check for `git://` GitHub repository URLs, https:// is preferred. git_gh_pattern = %r{^git://[^/]*github\.com/} audit_urls(urls, git_gh_pattern) do |_, url| problem "Please use https:// for #{url}" end - # Check for git:// Gitorious repo URLs, https:// is preferred. + # Check for `git://` Gitorious repository URLs, https:// is preferred. git_gitorious_pattern = %r{^git://[^/]*gitorious\.org/} audit_urls(urls, git_gitorious_pattern) do |_, url| problem "Please use https:// for #{url}" end - # Check for http:// GitHub repo URLs, https:// is preferred. + # Check for `http://` GitHub repository URLs, https:// is preferred. gh_pattern = %r{^http://github\.com/.*\.git$} audit_urls(urls, gh_pattern) do |_, url| problem "Please use https:// for #{url}" @@ -207,7 +207,7 @@ module RuboCop problem "Use versioned rather than branch tarballs for stable checksums." end - # Use new-style archive downloads + # Use new-style archive downloads. archive_gh_pattern = %r{https://.*github.*/(?:tar|zip)ball/} audit_urls(urls, archive_gh_pattern) do |_, url| next if url.end_with?(".git") diff --git a/Library/Homebrew/software_spec.rb b/Library/Homebrew/software_spec.rb index 96d7e49333..cc1d0a65d6 100644 --- a/Library/Homebrew/software_spec.rb +++ b/Library/Homebrew/software_spec.rb @@ -138,7 +138,7 @@ class SoftwareSpec end def go_resource(name, &block) - # odeprecated "SoftwareSpec#go_resource", "Go modules" + # odeprecated "`SoftwareSpec#go_resource`", "Go modules" resource name, Resource::Go, &block end @@ -207,18 +207,6 @@ class SoftwareSpec depends_on UsesFromMacOSDependency.new(dep, tags, bounds:) end - # @deprecated - def uses_from_macos_elements - # TODO: Remember to remove the delegate from `Formula`. - odisabled "#uses_from_macos_elements", "#declared_deps" - end - - # @deprecated - def uses_from_macos_names - # TODO: Remember to remove the delegate from `Formula`. - odisabled "#uses_from_macos_names", "#declared_deps" - end - def deps dependency_collector.deps.dup_without_system_deps end @@ -318,7 +306,6 @@ class Bottle "#{name}--#{version}#{extname}" end - # @!visibility private sig { returns(String) } def to_s = to_str @@ -634,11 +621,11 @@ class BottleSpecification def checksums tags = collector.tags.sort_by do |tag| version = tag.to_macos_version - # Give arm64 bottles a higher priority so they are first - priority = (tag.arch == :arm64) ? "2" : "1" + # Give `arm64` bottles a higher priority so they are first. + priority = (tag.arch == :arm64) ? 2 : 1 "#{priority}.#{version}_#{tag}" rescue MacOSVersion::Error - # Sort non-MacOS tags below MacOS tags. + # Sort non-macOS tags below macOS tags. "0.#{tag}" end tags.reverse.map do |tag| diff --git a/Library/Homebrew/sorbet/rbi/gems/redcarpet@3.6.0.rbi b/Library/Homebrew/sorbet/rbi/gems/redcarpet@3.6.0.rbi new file mode 100644 index 0000000000..705a9e6301 --- /dev/null +++ b/Library/Homebrew/sorbet/rbi/gems/redcarpet@3.6.0.rbi @@ -0,0 +1,8 @@ +# typed: true + +# DO NOT EDIT MANUALLY +# This is an autogenerated file for types exported from the `redcarpet` gem. +# Please instead update this file by running `bin/tapioca gem redcarpet`. + +# THIS IS AN EMPTY RBI FILE. +# see https://github.com/Shopify/tapioca#manually-requiring-parts-of-a-gem diff --git a/Library/Homebrew/sorbet/rbi/parlour.rbi b/Library/Homebrew/sorbet/rbi/parlour.rbi index 8514d0cca0..aee33eadc2 100644 --- a/Library/Homebrew/sorbet/rbi/parlour.rbi +++ b/Library/Homebrew/sorbet/rbi/parlour.rbi @@ -80,21 +80,12 @@ class Formula sig { params(args: T.untyped, options: T.untyped, block: T.untyped).returns(T::Boolean) } def loaded_from_api?(*args, **options, &block); end - sig { params(args: T.untyped, options: T.untyped, block: T.untyped).returns(T.untyped) } - def resource(*args, **options, &block); end - sig { params(args: T.untyped, options: T.untyped, block: T.untyped).returns(T.untyped) } def deps(*args, **options, &block); end sig { params(args: T.untyped, options: T.untyped, block: T.untyped).returns(T.untyped) } def declared_deps(*args, **options, &block); end - sig { params(args: T.untyped, options: T.untyped, block: T.untyped).returns(T.untyped) } - def uses_from_macos_elements(*args, **options, &block); end - - sig { params(args: T.untyped, options: T.untyped, block: T.untyped).returns(T.untyped) } - def uses_from_macos_names(*args, **options, &block); end - sig { params(args: T.untyped, options: T.untyped, block: T.untyped).returns(T.untyped) } def requirements(*args, **options, &block); end @@ -161,9 +152,6 @@ class Formula sig { params(args: T.untyped, options: T.untyped, block: T.untyped).returns(T.untyped) } def env(*args, **options, &block); end - sig { params(args: T.untyped, options: T.untyped, block: T.untyped).returns(T.untyped) } - def conflicts(*args, **options, &block); end - sig { returns(T::Boolean) } def self.loaded_from_api?; end diff --git a/Library/Homebrew/source_location.rb b/Library/Homebrew/source_location.rb index a75cc443c0..b3671cb5a4 100644 --- a/Library/Homebrew/source_location.rb +++ b/Library/Homebrew/source_location.rb @@ -16,7 +16,6 @@ module Homebrew @column = column end - # @!visibility private sig { returns(String) } def to_s "#{line}#{column&.to_s&.prepend(":")}" diff --git a/Library/Homebrew/startup/config.rb b/Library/Homebrew/startup/config.rb index 78161247f3..1251a8812a 100644 --- a/Library/Homebrew/startup/config.rb +++ b/Library/Homebrew/startup/config.rb @@ -12,7 +12,7 @@ HOMEBREW_PREFIX = Pathname(ENV.fetch("HOMEBREW_PREFIX")).freeze # Where `.git` is found HOMEBREW_REPOSITORY = Pathname(ENV.fetch("HOMEBREW_REPOSITORY")).freeze -# Where we store most of Homebrew, taps, and various metadata +# Where we store most of Homebrew, taps and various metadata HOMEBREW_LIBRARY = Pathname(ENV.fetch("HOMEBREW_LIBRARY")).freeze # Where shim scripts for various build and SCM tools are stored @@ -39,7 +39,7 @@ HOMEBREW_CACHE = Pathname(ENV.fetch("HOMEBREW_CACHE")).freeze # Where formulae installed via URL are cached HOMEBREW_CACHE_FORMULA = (HOMEBREW_CACHE/"Formula").freeze -# Where build, postinstall, and test logs of formulae are written to +# Where build, postinstall and test logs of formulae are written to HOMEBREW_LOGS = Pathname(ENV.fetch("HOMEBREW_LOGS")).expand_path.freeze # Path to the list of Homebrew maintainers as a JSON file diff --git a/Library/Homebrew/style.rb b/Library/Homebrew/style.rb index 426fc91312..066438b32e 100644 --- a/Library/Homebrew/style.rb +++ b/Library/Homebrew/style.rb @@ -179,7 +179,7 @@ module Homebrew # -f (--force) : we know what we are doing, force apply patches # -d / (--directory=/) : change to root directory, since we use absolute file paths # -p0 (--strip=0) : do not strip path prefixes, since we are at root directory - # NOTE: we use short flags where for compatibility + # NOTE: We use short flags for compatibility. patch_command = %w[patch -g 0 -f -d / -p0] patches = system_command(shellcheck, args: ["--format=diff", *args]).stdout Utils.safe_popen_write(*patch_command) { |p| p.write(patches) } if patches.present? diff --git a/Library/Homebrew/tab.rb b/Library/Homebrew/tab.rb index f55da44815..163e9182ea 100644 --- a/Library/Homebrew/tab.rb +++ b/Library/Homebrew/tab.rb @@ -13,12 +13,18 @@ class Tab FILENAME = "INSTALL_RECEIPT.json" + # Check whether the formula was installed as a dependency. + # # @api internal attr_accessor :installed_as_dependency + # Check whether the formula was installed on request. + # # @api internal attr_accessor :installed_on_request + # Check whether the formula was poured from a bottle. + # # @api internal attr_accessor :poured_from_bottle @@ -27,6 +33,8 @@ class Tab :built_on attr_writer :used_options, :unused_options, :compiler, :source_modified_time + # Returns the formula's runtime dependencies. + # # @api internal attr_writer :runtime_dependencies @@ -72,7 +80,8 @@ class Tab end # Returns the {Tab} for an install receipt at `path`. - # Results are cached. + # + # NOTE: Results are cached. def self.from_file(path) cache.fetch(path) do |p| content = File.read(p) @@ -282,7 +291,10 @@ class Tab spec == :stable end + # The options used to install the formula. + # # @api internal + sig { returns(Options) } def used_options Options.create(@used_options) end @@ -321,6 +333,7 @@ class Tab built_as_bottle end + sig { returns(T.nilable(Tap)) } def tap tap_name = source["tap"] Tap.fetch(tap_name) if tap_name @@ -407,7 +420,6 @@ class Tab tabfile.atomic_write(to_json) end - # @!visibility private sig { returns(String) } def to_s s = [] diff --git a/Library/Homebrew/tap.rb b/Library/Homebrew/tap.rb index dd97163a59..ab2046dae0 100644 --- a/Library/Homebrew/tap.rb +++ b/Library/Homebrew/tap.rb @@ -154,7 +154,6 @@ class Tap attr_reader :name # @api public - # @!visibility private sig { returns(String) } def to_s = name @@ -449,9 +448,9 @@ class Tap args << "--origin=origin" args << "-q" if quiet - # Override user-set default template + # Override user-set default template. args << "--template=" - # prevent fsmonitor from watching this repo + # Prevent `fsmonitor` from watching this repository. args << "--config" << "core.fsmonitor=false" begin diff --git a/Library/Homebrew/test/ENV_spec.rb b/Library/Homebrew/test/ENV_spec.rb index c5417db549..78649f3e83 100644 --- a/Library/Homebrew/test/ENV_spec.rb +++ b/Library/Homebrew/test/ENV_spec.rb @@ -73,8 +73,8 @@ RSpec.describe "ENV" do expect(subject["foo"]).to eq("1") end - # NOTE: this may be a wrong behavior; we should probably reject objects that - # do not respond to #to_str. For now this documents existing behavior. + # NOTE: This may be a wrong behavior; we should probably reject objects that + # do not respond to `#to_str`. For now this documents existing behavior. it "coerces a value to a string" do subject.append "foo", 42 expect(subject["foo"]).to eq("42") diff --git a/Library/Homebrew/test/cask/artifact/abstract_artifact_spec.rb b/Library/Homebrew/test/cask/artifact/abstract_artifact_spec.rb index 348011d80d..1bcde8ed7a 100644 --- a/Library/Homebrew/test/cask/artifact/abstract_artifact_spec.rb +++ b/Library/Homebrew/test/cask/artifact/abstract_artifact_spec.rb @@ -4,7 +4,7 @@ RSpec.describe Cask::Artifact::AbstractArtifact, :cask do describe ".read_script_arguments" do let(:stanza) { :installer } - it "accepts a string, and uses it as the executable" do + it "accepts a string and uses it as the executable" do arguments = "something" expect(described_class.read_script_arguments(arguments, stanza)).to eq(["something", {}]) diff --git a/Library/Homebrew/test/cask/cask_spec.rb b/Library/Homebrew/test/cask/cask_spec.rb index 9553e2510e..701a58a204 100644 --- a/Library/Homebrew/test/cask/cask_spec.rb +++ b/Library/Homebrew/test/cask/cask_spec.rb @@ -332,8 +332,8 @@ RSpec.describe Cask::Cask, :cask do expect(JSON.pretty_generate(h["variations"])).to eq expected_sha256_variations.strip end - # @note The calls to `Cask.generating_hash!` and `Cask.generated_hash!` - # are not idempotent so they can only be used in one test. + # NOTE: The calls to `Cask.generating_hash!` and `Cask.generated_hash!` + # are not idempotent so they can only be used in one test. it "returns the correct hash placeholders" do described_class.generating_hash! expect(described_class).to be_generating_hash diff --git a/Library/Homebrew/test/cask/dsl_spec.rb b/Library/Homebrew/test/cask/dsl_spec.rb index 891c33a3a1..ab3131968e 100644 --- a/Library/Homebrew/test/cask/dsl_spec.rb +++ b/Library/Homebrew/test/cask/dsl_spec.rb @@ -5,7 +5,7 @@ RSpec.describe Cask::DSL, :cask do let(:token) { "basic-cask" } describe "stanzas" do - it "lets you set url, homepage, and version" do + it "lets you set url, homepage and version" do expect(cask.url.to_s).to eq("https://brew.sh/TestCask-1.2.3.dmg") expect(cask.homepage).to eq("https://brew.sh/") expect(cask.version.to_s).to eq("1.2.3") diff --git a/Library/Homebrew/test/caveats_spec.rb b/Library/Homebrew/test/caveats_spec.rb index 58b41f24f9..97c2970ded 100644 --- a/Library/Homebrew/test/caveats_spec.rb +++ b/Library/Homebrew/test/caveats_spec.rb @@ -87,7 +87,7 @@ RSpec.describe Caveats do expect(caveats).to include("tmux") end - # @todo This should get deprecated and the service block `plist_name` method should get used instead. + # TODO: This should get deprecated and the service block `plist_name` method should get used instead. it "prints info when there are custom service files" do f = formula do url "foo-1.0" diff --git a/Library/Homebrew/test/language/python/virtualenv_spec.rb b/Library/Homebrew/test/language/python/virtualenv_spec.rb index bb03d7e498..27a9934f9f 100644 --- a/Library/Homebrew/test/language/python/virtualenv_spec.rb +++ b/Library/Homebrew/test/language/python/virtualenv_spec.rb @@ -140,7 +140,7 @@ RSpec.describe Language::Python::Virtualenv, :needs_python do end.to raise_error(ArgumentError) end - it "installs resources in correct order when combining `without`, `start_with`, and `end_with" do + it "installs resources in correct order when combining `without`, `start_with` and `end_with" do expect(f).to receive(:virtualenv_create).and_return(venv) expect(venv).to receive(:pip_install).with([r_d, r_c, r_b]) expect(venv).to receive(:pip_install_and_link).with(buildpath, { link_manpages: false }) diff --git a/Library/Homebrew/test/livecheck/strategy/electron_builder_spec.rb b/Library/Homebrew/test/livecheck/strategy/electron_builder_spec.rb index fde044cb4f..24143c280e 100644 --- a/Library/Homebrew/test/livecheck/strategy/electron_builder_spec.rb +++ b/Library/Homebrew/test/livecheck/strategy/electron_builder_spec.rb @@ -79,9 +79,9 @@ RSpec.describe Homebrew::Livecheck::Strategy::ElectronBuilder do end).to eq(find_versions_cached_return_hash.merge({ regex: })) # NOTE: A regex should be provided using the `#regex` method in a - # `livecheck` block but we're using a regex literal in the `strategy` - # block here simply to ensure this method works as expected when a - # regex isn't provided. + # `livecheck` block but we're using a regex literal in the `strategy` + # block here simply to ensure this method works as expected when a + # regex isn't provided. expect(electron_builder.find_versions(url: http_url, provided_content: content) do |yaml| regex = /^v?(\d+(?:\.\d+)+)$/i yaml["version"][regex, 1] diff --git a/Library/Homebrew/test/livecheck/strategy/extract_plist_spec.rb b/Library/Homebrew/test/livecheck/strategy/extract_plist_spec.rb index 8165439c4e..039cdc2507 100644 --- a/Library/Homebrew/test/livecheck/strategy/extract_plist_spec.rb +++ b/Library/Homebrew/test/livecheck/strategy/extract_plist_spec.rb @@ -72,7 +72,7 @@ RSpec.describe Homebrew::Livecheck::Strategy::ExtractPlist do ).to eq(versions) end - it "returns an array of version strings when given Items, a regex, and a block" do + it "returns an array of version strings when given `Item`s, a regex and a block" do # Returning a string from block expect( extract_plist.versions_from_items(multipart_items, multipart_regex) do |items, regex| diff --git a/Library/Homebrew/test/livecheck/strategy/header_match_spec.rb b/Library/Homebrew/test/livecheck/strategy/header_match_spec.rb index d7baece1eb..39553a28d0 100644 --- a/Library/Homebrew/test/livecheck/strategy/header_match_spec.rb +++ b/Library/Homebrew/test/livecheck/strategy/header_match_spec.rb @@ -75,7 +75,7 @@ RSpec.describe Homebrew::Livecheck::Strategy::HeaderMatch do end it "returns an array of version strings when given headers and a block" do - # Returning a string from block, no regex + # Returning a string from block, no regex. expect( header_match.versions_from_headers(headers[:location]) do |headers| v = Version.parse(headers["location"], detected_from_url: true) @@ -83,16 +83,17 @@ RSpec.describe Homebrew::Livecheck::Strategy::HeaderMatch do end, ).to eq(versions[:location]) - # Returning a string from block, explicit regex + # Returning a string from block, explicit regex. expect( header_match.versions_from_headers(headers[:location], regexes[:latest]) do |headers, regex| headers["location"] ? headers["location"][regex, 1] : nil end, ).to eq(versions[:location]) - # Returning an array of strings from block - # NOTE: Strategies runs `#compact` on an array from a block, so nil - # values are filtered out without needing to use `#compact` in the block. + # Returning an array of strings from block. + # + # NOTE: Strategies runs `#compact` on an array from a block, so nil values + # are filtered out without needing to use `#compact` in the block. expect( header_match.versions_from_headers( headers[:content_disposition_and_location], diff --git a/Library/Homebrew/test/livecheck/strategy/json_spec.rb b/Library/Homebrew/test/livecheck/strategy/json_spec.rb index 43c47250f5..dc18a8f074 100644 --- a/Library/Homebrew/test/livecheck/strategy/json_spec.rb +++ b/Library/Homebrew/test/livecheck/strategy/json_spec.rb @@ -126,9 +126,9 @@ RSpec.describe Homebrew::Livecheck::Strategy::Json do end).to eq(find_versions_cached_return_hash) # NOTE: A regex should be provided using the `#regex` method in a - # `livecheck` block but we're using a regex literal in the `strategy` - # block here simply to ensure this method works as expected when a - # regex isn't provided. + # `livecheck` block but we're using a regex literal in the `strategy` + # block here simply to ensure this method works as expected when a + # regex isn't provided. expect(json.find_versions(url: http_url, provided_content: content) do |json| regex = /^v?(\d+(?:\.\d+)+)$/i json["versions"].select { |item| item["version"]&.match?(regex) } diff --git a/Library/Homebrew/test/livecheck/strategy/page_match_spec.rb b/Library/Homebrew/test/livecheck/strategy/page_match_spec.rb index 4b2fab9321..6c79eaf646 100644 --- a/Library/Homebrew/test/livecheck/strategy/page_match_spec.rb +++ b/Library/Homebrew/test/livecheck/strategy/page_match_spec.rb @@ -109,11 +109,11 @@ RSpec.describe Homebrew::Livecheck::Strategy::PageMatch do .to eq(find_versions_cached_return_hash) # NOTE: Ideally, a regex should always be provided to `#find_versions` - # for `PageMatch` but there are currently some `livecheck` blocks in - # casks where `#regex` isn't used and the regex only exists within a - # `strategy` block. This isn't ideal but, for the moment, we allow a - # `strategy` block to act as a substitution for a regex and we need to - # test this scenario to ensure it works. + # for `PageMatch` but there are currently some `livecheck` blocks in + # casks where `#regex` isn't used and the regex only exists within a + # `strategy` block. This isn't ideal but, for the moment, we allow a + # `strategy` block to act as a substitution for a regex and we need to + # test this scenario to ensure it works. # # Under normal circumstances, a regex should be established in a # `livecheck` block using `#regex` and passed into the `strategy` block diff --git a/Library/Homebrew/test/livecheck/strategy/sparkle_spec.rb b/Library/Homebrew/test/livecheck/strategy/sparkle_spec.rb index 97bc76ca69..c895fb53a7 100644 --- a/Library/Homebrew/test/livecheck/strategy/sparkle_spec.rb +++ b/Library/Homebrew/test/livecheck/strategy/sparkle_spec.rb @@ -395,7 +395,7 @@ RSpec.describe Homebrew::Livecheck::Strategy::Sparkle do ).to eq([items[:v121].nice_version]) end - it "returns an array of version strings when given content, a regex, and a block" do + it "returns an array of version strings when given content, a regex and a block" do # Returning a string from the block expect( sparkle.versions_from_content(xml[:appcast], title_regex) do |item, regex| diff --git a/Library/Homebrew/test/livecheck/strategy/xml_spec.rb b/Library/Homebrew/test/livecheck/strategy/xml_spec.rb index b879049556..39c93075cd 100644 --- a/Library/Homebrew/test/livecheck/strategy/xml_spec.rb +++ b/Library/Homebrew/test/livecheck/strategy/xml_spec.rb @@ -218,9 +218,9 @@ RSpec.describe Homebrew::Livecheck::Strategy::Xml do end).to eq(find_versions_cached_return_hash) # NOTE: A regex should be provided using the `#regex` method in a - # `livecheck` block but we're using a regex literal in the `strategy` - # block here simply to ensure this method works as expected when a - # regex isn't provided. + # `livecheck` block but we're using a regex literal in the `strategy` + # block here simply to ensure this method works as expected when a + # regex isn't provided. expect(xml.find_versions(url: http_url, provided_content: content_version_text) do |xml| regex = /^v?(\d+(?:\.\d+)+)$/i xml.get_elements("/versions/version").map { |item| item.text[regex, 1] } diff --git a/Library/Homebrew/test/livecheck/strategy/yaml_spec.rb b/Library/Homebrew/test/livecheck/strategy/yaml_spec.rb index 72d7a67f36..8d2f3827f9 100644 --- a/Library/Homebrew/test/livecheck/strategy/yaml_spec.rb +++ b/Library/Homebrew/test/livecheck/strategy/yaml_spec.rb @@ -127,9 +127,9 @@ RSpec.describe Homebrew::Livecheck::Strategy::Yaml do end).to eq(find_versions_cached_return_hash) # NOTE: A regex should be provided using the `#regex` method in a - # `livecheck` block but we're using a regex literal in the `strategy` - # block here simply to ensure this method works as expected when a - # regex isn't provided. + # `livecheck` block but we're using a regex literal in the `strategy` + # block here simply to ensure this method works as expected when a + # regex isn't provided. expect(yaml.find_versions(url: http_url, provided_content: content) do |yaml| regex = /^v?(\d+(?:\.\d+)+)$/i yaml["versions"].select { |item| item["version"]&.match?(regex) } diff --git a/Library/Homebrew/test/os/linux/dependency_collector_spec.rb b/Library/Homebrew/test/os/linux/dependency_collector_spec.rb index 3ba82de27a..5df6690988 100644 --- a/Library/Homebrew/test/os/linux/dependency_collector_spec.rb +++ b/Library/Homebrew/test/os/linux/dependency_collector_spec.rb @@ -10,7 +10,7 @@ RSpec.describe DependencyCollector do describe "#add" do resource = Resource.new - context "when xz, unzip, and bzip2 are not available" do + context "when xz, unzip and bzip2 are not available" do it "creates a resource dependency from a '.xz' URL" do resource.url("https://brew.sh/foo.xz") allow_any_instance_of(Object).to receive(:which).with("xz") @@ -30,7 +30,7 @@ RSpec.describe DependencyCollector do end end - context "when xz, zip, and bzip2 are available" do + context "when xz, zip and bzip2 are available" do it "does not create a resource dependency from a '.xz' URL" do resource.url("https://brew.sh/foo.xz") allow_any_instance_of(Object).to receive(:which).with("xz").and_return(Pathname.new("foo")) diff --git a/Library/Homebrew/test/rubocops/caveats_spec.rb b/Library/Homebrew/test/rubocops/caveats_spec.rb index 04cc4b35d6..93a80060be 100644 --- a/Library/Homebrew/test/rubocops/caveats_spec.rb +++ b/Library/Homebrew/test/rubocops/caveats_spec.rb @@ -13,7 +13,7 @@ RSpec.describe RuboCop::Cop::FormulaAudit::Caveats do url "https://brew.sh/foo-1.0.tgz" def caveats "setuid" - ^^^^^^^^ FormulaAudit/Caveats: Don't recommend setuid in the caveats, suggest sudo instead. + ^^^^^^^^ FormulaAudit/Caveats: Don't recommend `setuid` in the caveats, suggest `sudo` instead. end end RUBY diff --git a/Library/Homebrew/test/service_spec.rb b/Library/Homebrew/test/service_spec.rb index 7b0c43cebb..a4b7a913a9 100644 --- a/Library/Homebrew/test/service_spec.rb +++ b/Library/Homebrew/test/service_spec.rb @@ -1058,8 +1058,8 @@ RSpec.describe Homebrew::Service do } end - # @note The calls to `Formula.generating_hash!` and `Formula.generated_hash!` - # are not idempotent so they can only be used in one test. + # NOTE: The calls to `Formula.generating_hash!` and `Formula.generated_hash!` + # are not idempotent so they can only be used in one test. it "replaces local paths with placeholders" do f = stub_formula do service do diff --git a/Library/Homebrew/test/sorbet/tapioca/compilers/args_spec.rb b/Library/Homebrew/test/sorbet/tapioca/compilers/args_spec.rb index c160203735..ebb2716fde 100644 --- a/Library/Homebrew/test/sorbet/tapioca/compilers/args_spec.rb +++ b/Library/Homebrew/test/sorbet/tapioca/compilers/args_spec.rb @@ -10,7 +10,7 @@ RSpec.describe Tapioca::Compilers::Args do Homebrew::Cmd::List.parser end - # good testing candidate, bc it has multiple for each of switch, flag, and comma_array args: + # Good testing candidate because it has multiple for each of `switch`, `flag` and `comma_array` args: let(:update_python_resources_parser) do require "dev-cmd/update-python-resources" Homebrew::DevCmd::UpdatePythonResources.parser diff --git a/Library/Homebrew/test/spec_helper.rb b/Library/Homebrew/test/spec_helper.rb index b525f7a11b..2dd6dc134d 100644 --- a/Library/Homebrew/test/spec_helper.rb +++ b/Library/Homebrew/test/spec_helper.rb @@ -102,7 +102,7 @@ RSpec.configure do |config| end config.mock_with :rspec do |mocks| # Prevents you from mocking or stubbing a method that does not exist on - # a real object. This is generally recommended, and will default to + # a real object. This is generally recommended and will default to # `true` in RSpec 4. mocks.verify_partial_doubles = true end diff --git a/Library/Homebrew/test/support/extend/cachable.rb b/Library/Homebrew/test/support/extend/cachable.rb index 764314674d..748b0f7ed4 100644 --- a/Library/Homebrew/test/support/extend/cachable.rb +++ b/Library/Homebrew/test/support/extend/cachable.rb @@ -35,8 +35,8 @@ module Cachable # A list of all classes that have been loaded into memory that mixin or # inherit `Cachable` at the class or module level. # - # Note: Classes that inherit from `Formula` are excluded since it's not - # necessary to track and clear individual formula caches. + # NOTE: Classes that inherit from `Formula` are excluded since it's not + # necessary to track and clear individual formula caches. def self.class_list @class_list ||= [] end @@ -44,8 +44,8 @@ module Cachable # Clear the cache of every class or module that mixes in or inherits # `Cachable` at the class or module level. # - # Note: Classes that inherit from `Formula` are excluded since it's not - # necessary to track and clear individual formula caches. + # NOTE: Classes that inherit from `Formula` are excluded since it's not + # necessary to track and clear individual formula caches. def self.clear_all_caches class_list.each(&:clear_cache) end diff --git a/Library/Homebrew/test/unpack_strategy/zstd_spec.rb b/Library/Homebrew/test/unpack_strategy/zstd_spec.rb index 2fe9b40f16..b439ed657f 100644 --- a/Library/Homebrew/test/unpack_strategy/zstd_spec.rb +++ b/Library/Homebrew/test/unpack_strategy/zstd_spec.rb @@ -6,11 +6,11 @@ RSpec.describe UnpackStrategy::Zstd do let(:path) { TEST_FIXTURE_DIR/"cask/container.tar.zst" } it "is correctly detected" do - # UnpackStrategy.detect(path) for a .tar.XXX file returns either UnpackStrategy::Tar if - # the host's tar is able to extract that compressed file or UnpackStrategy::XXX otherwise, - # such as UnpackStrategy::Zstd. On macOS UnpackStrategy.detect("container.tar.zst") - # returns UnpackStrategy::Zstd, and on ubuntu-22.04 it returns UnpackStrategy::Tar, - # because the host's version of tar is recent enough and zstd is installed. + # `UnpackStrategy.detect(path)` for a `.tar.XXX` file returns either `UnpackStrategy::Tar` if + # the host's `tar` is able to extract that compressed file or `UnpackStrategy::XXX` otherwise, + # such as `UnpackStrategy::Zstd`. On macOS `UnpackStrategy.detect("container.tar.zst")` + # returns `UnpackStrategy::Zstd` and on Ubuntu 22.04 it returns `UnpackStrategy::Tar`, + # because the host's version of `tar` is recent enough and `zstd` is installed. expect(UnpackStrategy.detect(path)).to(be_a(described_class).or(be_a(UnpackStrategy::Tar))) end end diff --git a/Library/Homebrew/test/utils/gzip_spec.rb b/Library/Homebrew/test/utils/gzip_spec.rb index 4679a15e1e..bb16e3421d 100644 --- a/Library/Homebrew/test/utils/gzip_spec.rb +++ b/Library/Homebrew/test/utils/gzip_spec.rb @@ -6,7 +6,7 @@ RSpec.describe Utils::Gzip do include FileUtils describe "compress_with_options" do - it "uses the explicitly specified mtime, orig_name, and output path when passed" do + it "uses the explicitly specified mtime, orig_name and output path when passed" do mktmpdir do |path| mtime = Time.at(12345).utc orig_name = "someotherfile" diff --git a/Library/Homebrew/test/utils/pypi_spec.rb b/Library/Homebrew/test/utils/pypi_spec.rb index f5f529e143..e904988e2a 100644 --- a/Library/Homebrew/test/utils/pypi_spec.rb +++ b/Library/Homebrew/test/utils/pypi_spec.rb @@ -141,7 +141,7 @@ RSpec.describe PyPI do expect(package_with_version.pypi_info(new_version: "5.29.0")).to eq expected_result end - it "gets pypi info from a package name, extras, and version" do + it "gets pypi info from a package name, extras and version" do expected_result = ["snakemake", old_pypi_package_url, old_package_checksum, "5.28.0"] expect(package_with_extra_and_version.pypi_info).to eq expected_result end diff --git a/Library/Homebrew/test/utils/shell_spec.rb b/Library/Homebrew/test/utils/shell_spec.rb index b5f8d9b6d6..f3f2fb9bce 100644 --- a/Library/Homebrew/test/utils/shell_spec.rb +++ b/Library/Homebrew/test/utils/shell_spec.rb @@ -72,7 +72,7 @@ RSpec.describe Utils::Shell do specify "::csh_quote" do expect(described_class.send(:csh_quote, "")).to eq("''") expect(described_class.send(:csh_quote, "\\")).to eq("\\\\") - # NOTE: this test is different than for sh + # NOTE: This test is different than for `sh`. expect(described_class.send(:csh_quote, "\n")).to eq("'\\\n'") expect(described_class.send(:csh_quote, "$")).to eq("\\$") expect(described_class.send(:csh_quote, "word")).to eq("word") diff --git a/Library/Homebrew/url.rb b/Library/Homebrew/url.rb index e9fcb2b377..adbff352fc 100644 --- a/Library/Homebrew/url.rb +++ b/Library/Homebrew/url.rb @@ -15,7 +15,6 @@ class URL @specs.freeze end - # @!visibility private sig { returns(String) } def to_s @url diff --git a/Library/Homebrew/utils/bottles.rb b/Library/Homebrew/utils/bottles.rb index 1518299a96..34ce838f85 100644 --- a/Library/Homebrew/utils/bottles.rb +++ b/Library/Homebrew/utils/bottles.rb @@ -202,7 +202,6 @@ module Utils end end - # @!visibility private sig { returns(String) } def to_s to_sym.to_s diff --git a/Library/Homebrew/utils/curl.rb b/Library/Homebrew/utils/curl.rb index 80cb908385..d23e0270e3 100644 --- a/Library/Homebrew/utils/curl.rb +++ b/Library/Homebrew/utils/curl.rb @@ -333,7 +333,7 @@ module Utils # GitHub does not authorize access to the web UI using token # # Strategy: - # If the `:homepage` 404s, it's a GitHub link, and we have a token then + # If the `:homepage` 404s, it's a GitHub link and we have a token then # check the API (which does use tokens) for the repository repo_details = url.match(%r{https?://github\.com/(?[^/]+)/(?[^/]+)/?.*}) check_github_api = url_type == SharedAudits::URL_TYPE_HOMEPAGE && @@ -483,7 +483,7 @@ module Utils # Separates the output text from `curl` into an array of HTTP responses and # the final response body (i.e. content). Response hashes contain the - # `:status_code`, `:status_text`, and `:headers`. + # `:status_code`, `:status_text` and `:headers`. # @param output [String] The output text from `curl` containing HTTP # responses, body content, or both. # @param max_iterations [Integer] The maximum number of iterations for the diff --git a/Library/Homebrew/utils/gems.rb b/Library/Homebrew/utils/gems.rb index 824c238fd2..373f8a0958 100644 --- a/Library/Homebrew/utils/gems.rb +++ b/Library/Homebrew/utils/gems.rb @@ -231,7 +231,7 @@ module Homebrew invalid_groups = groups - valid_gem_groups raise ArgumentError, "Invalid gem groups: #{invalid_groups.join(", ")}" unless invalid_groups.empty? - # tests should not modify the state of the repo + # Tests should not modify the state of the repository. if ENV["HOMEBREW_TESTS"] setup_gem_environment! return @@ -239,7 +239,7 @@ module Homebrew install_bundler! - # Combine the passed groups with the ones stored in settings + # Combine the passed groups with the ones stored in settings. groups |= (user_gem_groups & valid_gem_groups) groups.sort! diff --git a/Library/Homebrew/utils/github/actions.rb b/Library/Homebrew/utils/github/actions.rb index 412884d976..9e20bef10b 100644 --- a/Library/Homebrew/utils/github/actions.rb +++ b/Library/Homebrew/utils/github/actions.rb @@ -73,7 +73,6 @@ module GitHub @end_column = Integer(end_column) if end_column end - # @!visibility private sig { returns(String) } def to_s metadata = @type.to_s diff --git a/Library/Homebrew/utils/inreplace.rb b/Library/Homebrew/utils/inreplace.rb index 4031fa9c2d..6f866382c4 100644 --- a/Library/Homebrew/utils/inreplace.rb +++ b/Library/Homebrew/utils/inreplace.rb @@ -23,13 +23,21 @@ module Utils # defined by the formula, as only `HOMEBREW_PREFIX` is available # in the {DATAPatch embedded patch}. # - # @example `inreplace` supports regular expressions: - # inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool" + # ### Examples # - # @example `inreplace` supports blocks: - # inreplace "Makefile" do |s| - # s.gsub! "/usr/local", HOMEBREW_PREFIX.to_s - # end + # `inreplace` supports regular expressions: + # + # ```ruby + # inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool" + # ``` + # + # `inreplace` supports blocks: + # + # ```ruby + # inreplace "Makefile" do |s| + # s.gsub! "/usr/local", HOMEBREW_PREFIX.to_s + # end + # ``` # # @see StringInreplaceExtension # @api public diff --git a/Library/Homebrew/utils/pypi.rb b/Library/Homebrew/utils/pypi.rb index ac7da48422..db9f6337e7 100644 --- a/Library/Homebrew/utils/pypi.rb +++ b/Library/Homebrew/utils/pypi.rb @@ -49,7 +49,7 @@ module PyPI @is_pypi_url || !@is_url end - # Get name, URL, SHA-256 checksum, and latest version for a given package. + # Get name, URL, SHA-256 checksum and latest version for a given package. # This only works for packages from PyPI or from a PyPI URL; packages # derived from non-PyPI URLs will produce `nil` here. sig { params(new_version: T.nilable(T.any(String, Version))).returns(T.nilable(T::Array[String])) } @@ -82,7 +82,6 @@ module PyPI ] end - # @!visibility private sig { returns(String) } def to_s if valid_pypi_package? diff --git a/Library/Homebrew/utils/shebang.rb b/Library/Homebrew/utils/shebang.rb index 34d2356672..3a5d784b1f 100644 --- a/Library/Homebrew/utils/shebang.rb +++ b/Library/Homebrew/utils/shebang.rb @@ -20,8 +20,11 @@ module Utils # Rewrite shebang for the given `paths` using the given `rewrite_info`. # - # @example - # rewrite_shebang detected_python_shebang, bin/"script.py" + # ### Example + # + # ```ruby + # rewrite_shebang detected_python_shebang, bin/"script.py" + # ``` # # @api public sig { params(rewrite_info: RewriteInfo, paths: T.any(String, Pathname)).void } diff --git a/Library/Homebrew/utils/shell.rb b/Library/Homebrew/utils/shell.rb index e7c3de4257..aee062fa90 100644 --- a/Library/Homebrew/utils/shell.rb +++ b/Library/Homebrew/utils/shell.rb @@ -110,26 +110,26 @@ module Utils sig { params(str: String).returns(String) } def csh_quote(str) - # ruby's implementation of shell_escape + # Ruby's implementation of `shell_escape`. str = str.to_s return "''" if str.empty? str = str.dup - # anything that isn't a known safe character is padded + # Anything that isn't a known safe character is padded. str.gsub!(UNSAFE_SHELL_CHAR, "\\\\" + "\\1") # rubocop:disable Style/StringConcatenation - # newlines have to be specially quoted in csh + # Newlines have to be specially quoted in `csh`. str.gsub!("\n", "'\\\n'") str end sig { params(str: String).returns(String) } def sh_quote(str) - # ruby's implementation of shell_escape + # Ruby's implementation of `shell_escape`. str = str.to_s return "''" if str.empty? str = str.dup - # anything that isn't a known safe character is padded + # Anything that isn't a known safe character is padded. str.gsub!(UNSAFE_SHELL_CHAR, "\\\\" + "\\1") # rubocop:disable Style/StringConcatenation str.gsub!("\n", "'\n'") str diff --git a/Library/Homebrew/utils/tty.rb b/Library/Homebrew/utils/tty.rb index c6b3bd8877..637a90e6d3 100644 --- a/Library/Homebrew/utils/tty.rb +++ b/Library/Homebrew/utils/tty.rb @@ -98,7 +98,6 @@ module Tty end end - # @!visibility private sig { returns(String) } def to_s return "" unless color? diff --git a/Library/Homebrew/vendor/bundle/bundler/setup.rb b/Library/Homebrew/vendor/bundle/bundler/setup.rb index 633eac9ce0..bff3e2dc2d 100644 --- a/Library/Homebrew/vendor/bundle/bundler/setup.rb +++ b/Library/Homebrew/vendor/bundle/bundler/setup.rb @@ -71,6 +71,7 @@ $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/prism-0.27.0/lib") $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/pry-0.14.2/lib") $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rbi-0.1.12/lib") +$:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/redcarpet-3.6.0/lib") $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rspec-support-3.13.1/lib") $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rspec-core-3.13.0/lib") $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rspec-expectations-3.13.0/lib") diff --git a/Library/Homebrew/version.rb b/Library/Homebrew/version.rb index f42dbeddb4..274cd1aff2 100644 --- a/Library/Homebrew/version.rb +++ b/Library/Homebrew/version.rb @@ -57,7 +57,6 @@ class Version sig { abstract.params(other: T.untyped).returns(T.nilable(Integer)) } def <=>(other); end - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name} #{value.inspect}>" @@ -83,7 +82,6 @@ class Version value.to_s end - # @!visibility private sig { returns(String) } def to_s = to_str @@ -135,7 +133,6 @@ class Version sig { returns(T::Boolean) } def blank? = true - # @!visibility private sig { returns(String) } def inspect "#<#{self.class.name}>" @@ -350,7 +347,7 @@ class Version sig { params(val: String).returns(Version) } def self.create(val) - odisabled "Version.create", "Version.new" + odisabled "`Version.create`", "`Version.new`" new(val) end @@ -385,115 +382,115 @@ class Version VERSION_PARSERS = [ # date-based versioning - # e.g. 2023-09-28.tar.gz - # e.g. ltopers-v2017-04-14.tar.gz + # e.g. `2023-09-28.tar.gz` + # e.g. `ltopers-v2017-04-14.tar.gz` StemParser.new(/(?:^|[._-]?)v?(\d{4}-\d{2}-\d{2})/), # GitHub tarballs - # e.g. https://github.com/foo/bar/tarball/v1.2.3 - # e.g. https://github.com/sam-github/libnet/tarball/libnet-1.1.4 - # e.g. https://github.com/isaacs/npm/tarball/v0.2.5-1 - # e.g. https://github.com/petdance/ack/tarball/1.93_02 + # e.g. `https://github.com/foo/bar/tarball/v1.2.3` + # e.g. `https://github.com/sam-github/libnet/tarball/libnet-1.1.4` + # e.g. `https://github.com/isaacs/npm/tarball/v0.2.5-1` + # e.g. `https://github.com/petdance/ack/tarball/1.93_02` UrlParser.new(%r{github\.com/.+/(?:zip|tar)ball/(?:v|\w+-)?((?:\d+[._-])+\d*)$}), - # e.g. https://github.com/erlang/otp/tarball/OTP_R15B01 (erlang style) + # e.g. `https://github.com/erlang/otp/tarball/OTP_R15B01 (erlang style)` UrlParser.new(/[_-]([Rr]\d+[AaBb]\d*(?:-\d+)?)/), - # e.g. boost_1_39_0 + # e.g. `boost_1_39_0` StemParser.new(/((?:\d+_)+\d+)$/) { |s| s.tr("_", ".") }, - # e.g. foobar-4.5.1-1 - # e.g. unrtf_0.20.4-1 - # e.g. ruby-1.9.1-p243 + # e.g. `foobar-4.5.1-1` + # e.g. `unrtf_0.20.4-1` + # e.g. `ruby-1.9.1-p243` StemParser.new(/[_-](#{NUMERIC_WITH_DOTS}-(?:p|P|rc|RC)?\d+)#{CONTENT_SUFFIX}?$/), # Hyphenated versions without software-name prefix (e.g. brew-) - # e.g. v0.0.8-12.tar.gz - # e.g. 3.3.04-1.tar.gz - # e.g. v2.1-20210510.tar.gz - # e.g. 2020.11.11-3.tar.gz - # e.g. v3.6.6-0.2 + # e.g. `v0.0.8-12.tar.gz` + # e.g. `3.3.04-1.tar.gz` + # e.g. `v2.1-20210510.tar.gz` + # e.g. `2020.11.11-3.tar.gz` + # e.g. `v3.6.6-0.2` StemParser.new(/^v?(#{NUMERIC_WITH_DOTS}(?:-#{NUMERIC_WITH_OPTIONAL_DOTS})+)/), # URL with no extension - # e.g. https://waf.io/waf-1.8.12 - # e.g. https://codeload.github.com/gsamokovarov/jump/tar.gz/v0.7.1 + # e.g. `https://waf.io/waf-1.8.12` + # e.g. `https://codeload.github.com/gsamokovarov/jump/tar.gz/v0.7.1` UrlParser.new(/[-v](#{NUMERIC_WITH_OPTIONAL_DOTS})$/), - # e.g. lame-398-1 + # e.g. `lame-398-1` StemParser.new(/-(\d+-\d+)/), - # e.g. foobar-4.5.1 + # e.g. `foobar-4.5.1` StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS})$/), - # e.g. foobar-4.5.1.post1 + # e.g. `foobar-4.5.1.post1` StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS}(.post\d+)?)$/), - # e.g. foobar-4.5.1b + # e.g. `foobar-4.5.1b` StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS}(?:[abc]|rc|RC)\d*)$/), - # e.g. foobar-4.5.0-alpha5, foobar-4.5.0-beta1, or foobar-4.50-beta + # e.g. `foobar-4.5.0-alpha5, foobar-4.5.0-beta1, or foobar-4.50-beta` StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS}-(?:alpha|beta|rc)\d*)$/), - # e.g. https://ftpmirror.gnu.org/libidn/libidn-1.29-win64.zip - # e.g. https://ftpmirror.gnu.org/libmicrohttpd/libmicrohttpd-0.9.17-w32.zip + # e.g. `https://ftpmirror.gnu.org/libidn/libidn-1.29-win64.zip` + # e.g. `https://ftpmirror.gnu.org/libmicrohttpd/libmicrohttpd-0.9.17-w32.zip` StemParser.new(/-(#{MINOR_OR_PATCH})-w(?:in)?(?:32|64)$/), # Opam packages - # e.g. https://opam.ocaml.org/archives/sha.1.9+opam.tar.gz - # e.g. https://opam.ocaml.org/archives/lablgtk.2.18.3+opam.tar.gz - # e.g. https://opam.ocaml.org/archives/easy-format.1.0.2+opam.tar.gz + # e.g. `https://opam.ocaml.org/archives/sha.1.9+opam.tar.gz` + # e.g. `https://opam.ocaml.org/archives/lablgtk.2.18.3+opam.tar.gz` + # e.g. `https://opam.ocaml.org/archives/easy-format.1.0.2+opam.tar.gz` StemParser.new(/\.(#{MINOR_OR_PATCH})\+opam$/), - # e.g. https://ftpmirror.gnu.org/mtools/mtools-4.0.18-1.i686.rpm - # e.g. https://ftpmirror.gnu.org/autogen/autogen-5.5.7-5.i386.rpm - # e.g. https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x86.zip - # e.g. https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x64.zip - # e.g. https://ftpmirror.gnu.org/mtools/mtools_4.0.18_i386.deb + # e.g. `https://ftpmirror.gnu.org/mtools/mtools-4.0.18-1.i686.rpm` + # e.g. `https://ftpmirror.gnu.org/autogen/autogen-5.5.7-5.i386.rpm` + # e.g. `https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x86.zip` + # e.g. `https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x64.zip` + # e.g. `https://ftpmirror.gnu.org/mtools/mtools_4.0.18_i386.deb` StemParser.new(/[_-](#{MINOR_OR_PATCH}(?:-\d+)?)[._-](?:i[36]86|x86|x64(?:[_-](?:32|64))?)$/), - # e.g. https://registry.npmjs.org/@angular/cli/-/cli-1.3.0-beta.1.tgz - # e.g. https://github.com/dlang/dmd/archive/v2.074.0-beta1.tar.gz - # e.g. https://github.com/dlang/dmd/archive/v2.074.0-rc1.tar.gz - # e.g. https://github.com/premake/premake-core/releases/download/v5.0.0-alpha10/premake-5.0.0-alpha10-src.zip + # e.g. `https://registry.npmjs.org/@angular/cli/-/cli-1.3.0-beta.1.tgz` + # e.g. `https://github.com/dlang/dmd/archive/v2.074.0-beta1.tar.gz` + # e.g. `https://github.com/dlang/dmd/archive/v2.074.0-rc1.tar.gz` + # e.g. `https://github.com/premake/premake-core/releases/download/v5.0.0-alpha10/premake-5.0.0-alpha10-src.zip` StemParser.new(/[-.vV]?(#{NUMERIC_WITH_DOTS}#{PRERELEASE_SUFFIX})/), - # e.g. foobar4.5.1 + # e.g. `foobar4.5.1` StemParser.new(/(#{NUMERIC_WITH_OPTIONAL_DOTS})$/), - # e.g. foobar-4.5.0-bin + # e.g. `foobar-4.5.0-bin` StemParser.new(/[-vV](#{NUMERIC_WITH_DOTS}[abc]?)#{CONTENT_SUFFIX}$/), # dash version style - # e.g. http://www.antlr.org/download/antlr-3.4-complete.jar - # e.g. https://cdn.nuxeo.com/nuxeo-9.2/nuxeo-server-9.2-tomcat.zip - # e.g. https://search.maven.org/remotecontent?filepath=com/facebook/presto/presto-cli/0.181/presto-cli-0.181-executable.jar - # e.g. https://search.maven.org/remotecontent?filepath=org/fusesource/fuse-extra/fusemq-apollo-mqtt/1.3/fusemq-apollo-mqtt-1.3-uber.jar - # e.g. https://search.maven.org/remotecontent?filepath=org/apache/orc/orc-tools/1.2.3/orc-tools-1.2.3-uber.jar + # e.g. `http://www.antlr.org/download/antlr-3.4-complete.jar` + # e.g. `https://cdn.nuxeo.com/nuxeo-9.2/nuxeo-server-9.2-tomcat.zip` + # e.g. `https://search.maven.org/remotecontent?filepath=com/facebook/presto/presto-cli/0.181/presto-cli-0.181-executable.jar` + # e.g. `https://search.maven.org/remotecontent?filepath=org/fusesource/fuse-extra/fusemq-apollo-mqtt/1.3/fusemq-apollo-mqtt-1.3-uber.jar` + # e.g. `https://search.maven.org/remotecontent?filepath=org/apache/orc/orc-tools/1.2.3/orc-tools-1.2.3-uber.jar` StemParser.new(/-(#{NUMERIC_WITH_DOTS})-/), - # e.g. dash_0.5.5.1.orig.tar.gz (Debian style) + # e.g. `dash_0.5.5.1.orig.tar.gz (Debian style)` StemParser.new(/_(#{NUMERIC_WITH_DOTS}[abc]?)\.orig$/), - # e.g. https://www.openssl.org/source/openssl-0.9.8s.tar.gz + # e.g. `https://www.openssl.org/source/openssl-0.9.8s.tar.gz` StemParser.new(/-v?(\d[^-]+)/), - # e.g. astyle_1.23_macosx.tar.gz + # e.g. `astyle_1.23_macosx.tar.gz` StemParser.new(/_v?(\d[^_]+)/), - # e.g. http://mirrors.jenkins-ci.org/war/1.486/jenkins.war - # e.g. https://github.com/foo/bar/releases/download/0.10.11/bar.phar - # e.g. https://github.com/clojure/clojurescript/releases/download/r1.9.293/cljs.jar - # e.g. https://github.com/fibjs/fibjs/releases/download/v0.6.1/fullsrc.zip - # e.g. https://wwwlehre.dhbw-stuttgart.de/~sschulz/WORK/E_DOWNLOAD/V_1.9/E.tgz - # e.g. https://github.com/JustArchi/ArchiSteamFarm/releases/download/2.3.2.0/ASF.zip - # e.g. https://people.gnome.org/~newren/eg/download/1.7.5.2/eg + # e.g. `http://mirrors.jenkins-ci.org/war/1.486/jenkins.war` + # e.g. `https://github.com/foo/bar/releases/download/0.10.11/bar.phar` + # e.g. `https://github.com/clojure/clojurescript/releases/download/r1.9.293/cljs.jar` + # e.g. `https://github.com/fibjs/fibjs/releases/download/v0.6.1/fullsrc.zip` + # e.g. `https://wwwlehre.dhbw-stuttgart.de/~sschulz/WORK/E_DOWNLOAD/V_1.9/E.tgz` + # e.g. `https://github.com/JustArchi/ArchiSteamFarm/releases/download/2.3.2.0/ASF.zip` + # e.g. `https://people.gnome.org/~newren/eg/download/1.7.5.2/eg` UrlParser.new(%r{/(?:[rvV]_?)?(\d+\.\d+(?:\.\d+){,2})}), - # e.g. https://www.ijg.org/files/jpegsrc.v8d.tar.gz + # e.g. `https://www.ijg.org/files/jpegsrc.v8d.tar.gz` StemParser.new(/\.v(\d+[a-z]?)/), - # e.g. https://secure.php.net/get/php-7.1.10.tar.bz2/from/this/mirror + # e.g. `https://secure.php.net/get/php-7.1.10.tar.bz2/from/this/mirror` UrlParser.new(/[-.vV]?(#{NUMERIC_WITH_DOTS}#{PRERELEASE_SUFFIX}?)/), ].freeze private_constant :VERSION_PARSERS @@ -516,12 +513,16 @@ class Version private_constant :HEAD_VERSION_REGEX # Check if this is a HEAD version. + # + # @api public sig { returns(T::Boolean) } def head? version&.match?(HEAD_VERSION_REGEX) || false end # Return the commit for a HEAD version. + # + # @api public sig { returns(T.nilable(String)) } def commit version&.match(HEAD_VERSION_REGEX)&.[](:commit) @@ -646,6 +647,8 @@ class Version end alias eql? == + # The major version. + # # @api public sig { returns(T.nilable(Token)) } def major @@ -654,6 +657,8 @@ class Version tokens.first end + # The minor version. + # # @api public sig { returns(T.nilable(Token)) } def minor @@ -662,6 +667,8 @@ class Version tokens.second end + # The patch version. + # # @api public sig { returns(T.nilable(Token)) } def patch @@ -670,6 +677,8 @@ class Version tokens.third end + # The major and minor version. + # # @api public sig { returns(T.self_type) } def major_minor @@ -679,6 +688,8 @@ class Version major_minor.empty? ? NULL : self.class.new(major_minor.join(".")) end + # The major, minor and patch version. + # # @api public sig { returns(T.self_type) } def major_minor_patch @@ -693,6 +704,9 @@ class Version version.hash end + # Convert the version to a floating-point number. + # + # @api public sig { returns(Float) } def to_f return Float::NAN if null? @@ -700,11 +714,15 @@ class Version version.to_f end + # Convert the version to an integer. + # + # @api public sig { returns(Integer) } def to_i version.to_i end + # @api public sig { returns(String) } def to_str raise NoMethodError, "undefined method `to_str' for #{self.class}:NULL" if null? @@ -712,7 +730,7 @@ class Version T.must(version).to_str end - # @!visibility private + # @api public sig { returns(String) } def to_s = version.to_s @@ -728,7 +746,6 @@ class Version super end - # @!visibility private sig { returns(String) } def inspect return "#" if null? @@ -760,6 +777,7 @@ class Version end # Represents the absence of a version. + # # NOTE: Constructor needs to called with an arbitrary non-empty version which is then set to `nil`. NULL = Version.new("NULL").tap { |v| v.instance_variable_set(:@version, nil) }.freeze end diff --git a/Library/Homebrew/warnings.rb b/Library/Homebrew/warnings.rb index 94f0629290..83c124234a 100644 --- a/Library/Homebrew/warnings.rb +++ b/Library/Homebrew/warnings.rb @@ -9,7 +9,10 @@ module Warnings parser_syntax: [ %r{warning: parser/current is loading parser/ruby\d+, which recognizes}, /warning: \d+\.\d+\.\d+-compliant syntax, but you are running \d+\.\d+\.\d+\./, + # FIXME: https://github.com/errata-ai/vale/issues/818 + # %r{warning: please see https://github\.com/whitequark/parser#compatibility-with-ruby-mri\.}, + # ], }.freeze diff --git a/Library/Homebrew/yard/docstring_parser.rb b/Library/Homebrew/yard/docstring_parser.rb index 739916fbfd..41770c4102 100644 --- a/Library/Homebrew/yard/docstring_parser.rb +++ b/Library/Homebrew/yard/docstring_parser.rb @@ -5,15 +5,90 @@ 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 + def parse_content(content) + # Convert plain text to tags. + content = content&.gsub(/^\s*(TODO|FIXME):\s*/i, "@todo ") + content = content&.gsub(/^\s*NOTE:\s*/i, "@note ") + # Ignore non-documentation comments. - content = content&.sub(/(\A(typed|.*rubocop)|TODO|FIXME):.*/m, "") + content = content&.sub(/\A(typed|.*rubocop):.*/m, "") content = super(content) + source = handler&.statement&.source + + if object&.type == :method && + (match = source&.match(/\so(deprecated|disabled)\s+"((?:\\"|[^"])*)"(?:\s*,\s*"((?:\\"|[^"])*))?"/m)) + type = match[1] + method = match[2] + method = method.sub(/\#{self(\.class)?}/, object.namespace.to_s) + replacement = match[3] + replacement = replacement.sub(/\#{self(\.class)?}/, object.namespace.to_s) + + # Only match `odeprecated`/`odisabled` for this method. + if method.match?(/(.|#|`)#{Regexp.escape(object.name.to_s)}`/) + if (method_name = method[/\A`([^`]*)`\Z/, 1]) && ( + (method_name.count(".") + method_name.count("#")) <= 1 + ) + method_name = method_name.delete_prefix(object.namespace.to_s) + method = (method_name.delete_prefix(".") == object.name(true).to_s) ? nil : "{#{method_name}}" + end + + if replacement && + (replacement_method_name = replacement[/\A`([^`]*)`\Z/, 1]) && ( + (replacement_method_name.count(".") + replacement_method_name.count("#")) <= 1 + ) + replacement_method_name = replacement_method_name.delete_prefix(object.namespace.to_s) + replacement = "{#{replacement_method_name}}" + end + + if method && !method.include?('#{') + description = "Calling #{method} is #{type}" + description += ", use #{replacement} instead" if replacement && !replacement.include?('#{') + description += "." + elsif replacement && !replacement.include?('#{') + description = "Use #{replacement} instead." + else + description = "" + end + + tags << create_tag("deprecated", description) + end + end + + api = tags.find { |tag| tag.tag_name == "api" }&.text + is_private = tags.any? { |tag| tag.tag_name == "private" } + visibility = directives.find { |d| d.tag.tag_name == "visibility" }&.tag&.text + + # Hide `#hash`, `#inspect` and `#to_s`. + if visibility.nil? && OVERRIDABLE_METHODS.include?(object&.name) + create_directive("visibility", "private") + visibility = "private" + end + # Mark everything as `@api private` by default. - visibility_tags = ["visibility", "api", "private"] - tags << create_tag("api", "private") if tags.none? { |tag| visibility_tags.include?(tag.tag_name) } + if api.nil? && !is_private + tags << create_tag("api", "private") + api = "private" + end + + # Warn about undocumented non-private APIs. + if handler && api && api != "private" && visibility != "private" && + content.chomp.empty? && !SELF_EXPLANATORY_METHODS.include?(object&.name) + stmt = handler.statement + log.warn "#{api.capitalize} API should be documented:\n " \ + "in `#{handler.parser.file}`:#{stmt.line}:\n\n#{stmt.show}\n" + end content end diff --git a/completions/fish/brew.fish b/completions/fish/brew.fish index cfd60856b8..96c071b87a 100644 --- a/completions/fish/brew.fish +++ b/completions/fish/brew.fish @@ -1196,7 +1196,7 @@ __fish_brew_complete_arg 'pr-publish' -l verbose -d 'Make some output more verbo __fish_brew_complete_arg 'pr-publish' -l workflow -d 'Target workflow filename (default: `publish-commit-bottles.yml`)' -__fish_brew_complete_cmd 'pr-pull' 'Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions' +__fish_brew_complete_cmd 'pr-pull' 'Download and publish bottles and apply the bottle commit from a pull request with artifacts generated by GitHub Actions' __fish_brew_complete_arg 'pr-pull' -l artifact-pattern -d 'Download artifacts with the specified pattern (default: `bottles{,_*}`)' __fish_brew_complete_arg 'pr-pull' -l autosquash -d 'Automatically reformat and reword commits in the pull request to our preferred format' __fish_brew_complete_arg 'pr-pull' -l branch-okay -d 'Do not warn if pulling to a branch besides the repository default (useful for testing)' @@ -1482,12 +1482,12 @@ __fish_brew_complete_arg 'test' -a '(__fish_brew_suggest_formulae_installed)' __fish_brew_complete_cmd 'tests' 'Run Homebrew\'s unit and integration tests' __fish_brew_complete_arg 'tests' -l changed -d 'Only runs tests on files that were changed from the master branch' __fish_brew_complete_arg 'tests' -l coverage -d 'Generate code coverage reports' -__fish_brew_complete_arg 'tests' -l debug -d 'Enable debugging using ruby/debug, or surface the standard `odebug` output' +__fish_brew_complete_arg 'tests' -l debug -d 'Enable debugging using `ruby/debug`, or surface the standard `odebug` output' __fish_brew_complete_arg 'tests' -l fail-fast -d 'Exit early on the first failing test' __fish_brew_complete_arg 'tests' -l generic -d 'Run only OS-agnostic tests' __fish_brew_complete_arg 'tests' -l help -d 'Show this message' __fish_brew_complete_arg 'tests' -l online -d 'Include tests that use the GitHub API and tests that use any of the taps for official external commands' -__fish_brew_complete_arg 'tests' -l only -d 'Run only test_script`_spec.rb`. Appending `:`line_number will start at a specific line' +__fish_brew_complete_arg 'tests' -l only -d 'Run only `test_script_spec.rb`. Appending `:line_number` will start at a specific line' __fish_brew_complete_arg 'tests' -l profile -d 'Run the test suite serially to find the n slowest tests' __fish_brew_complete_arg 'tests' -l quiet -d 'Make some output more quiet' __fish_brew_complete_arg 'tests' -l seed -d 'Randomise tests with the specified value instead of a random seed' diff --git a/completions/zsh/_brew b/completions/zsh/_brew index 6a4fe95e06..3d85195e6e 100644 --- a/completions/zsh/_brew +++ b/completions/zsh/_brew @@ -195,7 +195,7 @@ __brew_internal_commands() { 'postinstall:Rerun the post-install steps for formula' 'pr-automerge:Find pull requests that can be automatically merged using `brew pr-publish`' 'pr-publish:Publish bottles for a pull request with GitHub Actions' - 'pr-pull:Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions' + 'pr-pull:Download and publish bottles and apply the bottle commit from a pull request with artifacts generated by GitHub Actions' 'pr-upload:Apply the bottle commit and publish bottles to a host' 'prof:Run Homebrew with a Ruby profiler' 'pyenv-sync:Create symlinks for Homebrew'\''s installed Python versions in `~/.pyenv/versions`' @@ -1835,12 +1835,12 @@ _brew_tests() { _arguments \ '(--only)--changed[Only runs tests on files that were changed from the master branch]' \ '--coverage[Generate code coverage reports]' \ - '--debug[Enable debugging using ruby/debug, or surface the standard `odebug` output]' \ + '--debug[Enable debugging using `ruby/debug`, or surface the standard `odebug` output]' \ '--fail-fast[Exit early on the first failing test]' \ '--generic[Run only OS-agnostic tests]' \ '--help[Show this message]' \ '--online[Include tests that use the GitHub API and tests that use any of the taps for official external commands]' \ - '(--changed)--only[Run only test_script`_spec.rb`. Appending `:`line_number will start at a specific line]' \ + '(--changed)--only[Run only `test_script_spec.rb`. Appending `:line_number` will start at a specific line]' \ '--profile[Run the test suite serially to find the n slowest tests]' \ '--quiet[Make some output more quiet]' \ '--seed[Randomise tests with the specified value instead of a random seed]' \ diff --git a/docs/External-Commands.md b/docs/External-Commands.md index 8c58a0f4c4..ec5f5f4c84 100644 --- a/docs/External-Commands.md +++ b/docs/External-Commands.md @@ -24,7 +24,7 @@ The command may `Kernel.exit` with a status code if it needs to; if it doesn't e ### Other executable scripts -An executable script for a command named `extcmd` should be named `brew-extcmd`. The script itself can use any suitable shebang (`#!`) line, so an external script can be written in Bash, Ruby, or even Python. Unlike the ruby commands this file must not end with a language-specific suffix (`.sh`, or `.py`). This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments. +An executable script for a command named `extcmd` should be named `brew-extcmd`. The script itself can use any suitable shebang (`#!`) line, so an external script can be written in Bash, Ruby, or even Python. Unlike the Ruby commands this file must not end with a language-specific suffix (`.sh`, or `.py`). This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments. | variable | description | | ---------------------- | ----------- | diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 71cc55435e..600be521e1 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -1175,7 +1175,7 @@ brew search --fink foo `superenv` is our "super environment" that isolates builds by removing `/usr/local/bin` and all user `PATH`s that are not essential for the build. It does this because user `PATH`s are often full of stuff that breaks builds. `superenv` also removes bad flags from the commands passed to `clang`/`gcc` and injects others (for example all [`keg_only`](https://rubydoc.brew.sh/Formula#keg_only-class_method) dependencies are added to the `-I` and `-L` flags). -If in your local Homebrew build of your new formula, you see `Operation not permitted` errors, this will be because your new formula tried to write to the disk outside of your sandbox area. This is enforced on MacOS by `sandbox-exec`. +If in your local Homebrew build of your new formula, you see `Operation not permitted` errors, this will be because your new formula tried to write to the disk outside of your sandbox area. This is enforced on macOS by `sandbox-exec`. ### Fortran diff --git a/docs/How-To-Organize-AGM.md b/docs/How-To-Organize-AGM.md index 42b515c570..160686964e 100644 --- a/docs/How-To-Organize-AGM.md +++ b/docs/How-To-Organize-AGM.md @@ -87,7 +87,7 @@ using this quick command:_ **When:** Week 1 of YEAR :date: `2024-01-01` -* [ ] PLC: Solicit changes to [Homebrew Governance](Homebrew-Governance.md) in the form of PRs on the `homebrew-governance-private` repo. +* [ ] PLC: Solicit changes to [Homebrew Governance](Homebrew-Governance.md) in the form of PRs on the `homebrew-governance-private` repository. ### Three weeks prior diff --git a/docs/Manpage.md b/docs/Manpage.md index f109d95270..8cd17e80dc 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -879,7 +879,7 @@ Show install options specific to *`formula`*. ### `outdated` \[*`options`*\] \[*`formula`*\|*`cask`* ...\] List installed casks and formulae that have an updated version available. By -default, version information is displayed in interactive shells, and suppressed +default, version information is displayed in interactive shells and suppressed otherwise. `-q`, `--quiet` @@ -2379,7 +2379,7 @@ the repository. ### `pr-pull` \[*`options`*\] *`pull_request`* \[...\] -Download and publish bottles, and apply the bottle commit from a pull request +Download and publish bottles and apply the bottle commit from a pull request with artifacts generated by GitHub Actions. Requires write access to the repository. @@ -2681,7 +2681,7 @@ Run Homebrew's unit and integration tests. `--debug` -: Enable debugging using ruby/debug, or surface the standard `odebug` output. +: Enable debugging using `ruby/debug`, or surface the standard `odebug` output. `--changed` @@ -2693,8 +2693,8 @@ Run Homebrew's unit and integration tests. `--only` -: Run only *`test_script`*`_spec.rb`. Appending `:`*`line_number`* will start at - a specific line. +: Run only `_spec.rb`. Appending `:` will start at a + specific line. `--profile` @@ -2874,7 +2874,7 @@ Install and commit Homebrew's vendored gems. ## GLOBAL CASK OPTIONS -These options are applicable to the `install`, `reinstall`, and `upgrade` +These options are applicable to the `install`, `reinstall` and `upgrade` subcommands with the `--cask` switch. `--appdir` diff --git a/docs/Taps.md b/docs/Taps.md index 74d2637b7f..c56363932f 100644 --- a/docs/Taps.md +++ b/docs/Taps.md @@ -16,23 +16,18 @@ but the command isn't limited to any one location. petere/postgresql ``` - - - -* `brew tap ` makes a clone of the repository at - _https://github.com/\/homebrew-\_ into `$(brew --repository)/Library/Taps`. +* `brew tap /` makes a clone of the repository at + `https://github.com//homebrew-` into `$(brew --repository)/Library/Taps`. After that, `brew` will be able to work with those formulae as if they were in Homebrew's [homebrew/core](https://github.com/Homebrew/homebrew-core) canonical repository. You can install and uninstall them with `brew [un]install`, and the formulae are automatically updated when you run `brew update`. (See below for details about how `brew tap` handles the names of repositories.) - - -* `brew tap ` makes a clone of the repository at _URL_. +* `brew tap / ` makes a clone of the repository at _URL_. Unlike the one-argument version, _URL_ is not assumed to be GitHub, and it doesn't have to be HTTP. Any location and any protocol that Git can handle is - fine, although non-GitHub taps require running `brew tap --force-auto-update ` + fine, although non-GitHub taps require running `brew tap --force-auto-update /` to enable automatic updating. * `brew tap --repair` migrates tapped formulae from a symlink-based to diff --git a/docs/governance/2021-agm-minutes.md b/docs/governance/2021-agm-minutes.md index 8e3ea8b38e..65f4c9e698 100644 --- a/docs/governance/2021-agm-minutes.md +++ b/docs/governance/2021-agm-minutes.md @@ -45,7 +45,7 @@ - 12:40–12:45 Michka Popoff - Merging the cores - 12:45–12:50 Michka Popoff - Linux CI for homebrew-core - 12:50–13:55 Misty De Meo - Running Homebrew on Apple Silicon -- 12:55–13:00 Shaun Jackman - Speeding up install times / Git repo size +- 12:55–13:00 Shaun Jackman - Speeding up install times/Git repository size - 13:10 Meeting adjourned ## Resolutions diff --git a/docs/vale-styles/Homebrew/Abbreviations.yml b/docs/vale-styles/Homebrew/Abbreviations.yml index df562c44aa..f51c2dd53f 100644 --- a/docs/vale-styles/Homebrew/Abbreviations.yml +++ b/docs/vale-styles/Homebrew/Abbreviations.yml @@ -1,6 +1,6 @@ --- extends: substitution -message: Use '%s' +message: Use '%s' instead of '%s'. ignorecase: false link: "https://github.com/Homebrew/brew/blob/HEAD/docs/Prose-Style-Guidelines.md#style-and-usage" level: error @@ -10,3 +10,9 @@ swap: '\bie\b': i.e. 'e\.g\.,': e.g. 'i\.e\.,': i.e. + '(?_spec\.rb\fP\&\. Appending \fB:\fP will start at a specific line\. .TP \fB\-\-profile\fP Run the test suite serially to find the \fIn\fP slowest tests\. @@ -1836,7 +1836,7 @@ Update the specified list of vendored gems to the latest version\. \fB\-\-no\-commit\fP Do not generate a new commit upon completion\. .SH "GLOBAL CASK OPTIONS" -These options are applicable to the \fBinstall\fP, \fBreinstall\fP, and \fBupgrade\fP subcommands with the \fB\-\-cask\fP switch\. +These options are applicable to the \fBinstall\fP, \fBreinstall\fP and \fBupgrade\fP subcommands with the \fB\-\-cask\fP switch\. .TP \fB\-\-appdir\fP Target location for Applications (default: \fB/Applications\fP)\.