Homebrew · MikeMcQuaid · Apr 26, 2024 · Mar 6, 2024
diff --git a/Library/Homebrew/.rubocop.yml b/Library/Homebrew/.rubocop.yml
@@ -28,8 +28,11 @@ Style/Documentation:
  - cask/dsl.rb
  - cask/dsl/version.rb
  - cask/url.rb
+ - development_tools.rb
  - download_strategy.rb
+ - extend/ENV/super.rb
  - extend/kernel.rb
+ - extend/pathname.rb
  - formula.rb
  - formula_assertions.rb
  - formula_free_port.rb

diff --git a/Library/Homebrew/.yardopts b/Library/Homebrew/.yardopts
@@ -3,7 +3,7 @@
 --markup markdown
 --no-private
 --plugin sorbet
---load yard/ignore_directives.rb
+--load ./yard/docstring_parser.rb
 --template-path yard/templates
 --exclude sorbet/rbi/gems/
 --exclude test/

diff --git a/Library/Homebrew/Gemfile b/Library/Homebrew/Gemfile
@@ -15,6 +15,10 @@ 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 "yard", require: false
+ gem "yard-sorbet", require: false
+end
 group :ast, optional: true do
  gem "rubocop-ast", require: false
 end

diff --git a/Library/Homebrew/Gemfile.lock b/Library/Homebrew/Gemfile.lock
@@ -198,6 +198,8 @@ DEPENDENCIES
  stackprof
  tapioca
  warning
+ yard
+ yard-sorbet
 
 RUBY VERSION
  ruby 3.1.4p223

diff --git a/Library/Homebrew/PATH.rb b/Library/Homebrew/PATH.rb
@@ -2,8 +2,6 @@
 # frozen_string_literal: true
 
 # Representation of a `*PATH` environment variable.
-#
-# @api private
 class PATH
  include Enumerable
  extend Forwardable

diff --git a/Library/Homebrew/api.rb b/Library/Homebrew/api.rb
@@ -9,8 +9,6 @@
 
 module Homebrew
  # Helper functions for using Homebrew's formulae.brew.sh API.
- #
- # @api private
  module API
  extend Cachable
 
@@ -191,15 +189,13 @@ def self.internal_json_v3?
  end
  end
 
- # @api private
  sig { params(block: T.proc.returns(T.untyped)).returns(T.untyped) }
  def self.with_no_api_env(&block)
  return yield if Homebrew::EnvConfig.no_install_from_api?
 
  with_env(HOMEBREW_NO_INSTALL_FROM_API: "1", HOMEBREW_AUTOMATICALLY_SET_NO_INSTALL_FROM_API: "1", &block)
  end
 
- # @api private
  sig { params(condition: T::Boolean, block: T.proc.returns(T.untyped)).returns(T.untyped) }
  def self.with_no_api_env_if_needed(condition, &block)
  return yield unless condition

diff --git a/Library/Homebrew/api/analytics.rb b/Library/Homebrew/api/analytics.rb
@@ -4,8 +4,6 @@
 module Homebrew
  module API
  # Helper functions for using the analytics JSON API.
- #
- # @api private
  module Analytics
  class << self
  sig { returns(String) }

diff --git a/Library/Homebrew/api/cask.rb b/Library/Homebrew/api/cask.rb
@@ -7,8 +7,6 @@
 module Homebrew
  module API
  # Helper functions for using the cask JSON API.
- #
- # @api private
  module Cask
  extend Cachable
 

diff --git a/Library/Homebrew/api/download.rb b/Library/Homebrew/api/download.rb
@@ -5,15 +5,13 @@
 
 module Homebrew
  module API
- # @api private
  class DownloadStrategy < CurlDownloadStrategy
  sig { override.returns(Pathname) }
  def symlink_location
  cache/name
  end
  end
 
- # @api private
  class Download < Downloadable
  sig {
  params(

diff --git a/Library/Homebrew/api/formula.rb b/Library/Homebrew/api/formula.rb
@@ -7,8 +7,6 @@
 module Homebrew
  module API
  # Helper functions for using the formula JSON API.
- #
- # @api private
  module Formula
  extend Cachable
 

diff --git a/Library/Homebrew/build.rb b/Library/Homebrew/build.rb
@@ -17,8 +17,6 @@
 require "cmd/install"
 
 # A formula build.
-#
-# @api private
 class Build
  attr_reader :formula, :deps, :reqs, :args
 

diff --git a/Library/Homebrew/build_environment.rb b/Library/Homebrew/build_environment.rb
@@ -2,8 +2,6 @@
 # frozen_string_literal: true
 
 # Settings for the build environment.
-#
-# @api private
 class BuildEnvironment
  sig { params(settings: Symbol).void }
  def initialize(*settings)

diff --git a/Library/Homebrew/build_options.rb b/Library/Homebrew/build_options.rb
@@ -2,10 +2,7 @@
 # frozen_string_literal: true
 
 # Options for a formula build.
-#
-# @api private
 class BuildOptions
- # @private
  def initialize(args, options)
  @args = args
  @options = options
@@ -70,12 +67,10 @@ def any_args_or_options?
  !@args.empty? || !@options.empty?
  end
 
- # @private
  def used_options
  @options & @args
  end
 
- # @private
  def unused_options
  @options - @args
  end

diff --git a/Library/Homebrew/bump_version_parser.rb b/Library/Homebrew/bump_version_parser.rb
@@ -3,8 +3,6 @@
 
 module Homebrew
  # Class handling architecture-specific version information.
- #
- # @api private
  class BumpVersionParser
  sig { returns(T.nilable(T.any(Version, Cask::DSL::Version))) }
  attr_reader :arm, :general, :intel

diff --git a/Library/Homebrew/bundle_version.rb b/Library/Homebrew/bundle_version.rb
@@ -5,8 +5,6 @@
 
 module Homebrew
  # Representation of a macOS bundle version, commonly found in `Info.plist` files.
- #
- # @api private
  class BundleVersion
  include Comparable
 

diff --git a/Library/Homebrew/cask/artifact.rb b/Library/Homebrew/cask/artifact.rb
@@ -30,8 +30,6 @@
 
 module Cask
  # Module containing all cask artifact classes.
- #
- # @api private
  module Artifact
  end
 end
diff --git a/Library/Homebrew/cask/artifact/abstract_artifact.rb b/Library/Homebrew/cask/artifact/abstract_artifact.rb
@@ -7,8 +7,6 @@
 module Cask
  module Artifact
  # Abstract superclass for all artifacts.
- #
- # @api private
  class AbstractArtifact
  extend T::Helpers
  abstract!

diff --git a/Library/Homebrew/cask/artifact/abstract_flight_block.rb b/Library/Homebrew/cask/artifact/abstract_flight_block.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Abstract superclass for block artifacts.
- #
- # @api private
  class AbstractFlightBlock < AbstractArtifact
  def self.dsl_key
  super.to_s.sub(/_block$/, "").to_sym

diff --git a/Library/Homebrew/cask/artifact/abstract_uninstall.rb b/Library/Homebrew/cask/artifact/abstract_uninstall.rb
@@ -12,8 +12,6 @@
 module Cask
  module Artifact
  # Abstract superclass for uninstall artifacts.
- #
- # @api private
  class AbstractUninstall < AbstractArtifact
  include SystemCommand::Mixin
 

diff --git a/Library/Homebrew/cask/artifact/app.rb b/Library/Homebrew/cask/artifact/app.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `app` stanza.
- #
- # @api private
  class App < Moved
  end
  end

diff --git a/Library/Homebrew/cask/artifact/artifact.rb b/Library/Homebrew/cask/artifact/artifact.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Generic artifact corresponding to the `artifact` stanza.
- #
- # @api private
  class Artifact < Moved
  sig { returns(String) }
  def self.english_name

diff --git a/Library/Homebrew/cask/artifact/audio_unit_plugin.rb b/Library/Homebrew/cask/artifact/audio_unit_plugin.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `audio_unit_plugin` stanza.
- #
- # @api private
  class AudioUnitPlugin < Moved
  end
  end

diff --git a/Library/Homebrew/cask/artifact/binary.rb b/Library/Homebrew/cask/artifact/binary.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `binary` stanza.
- #
- # @api private
  class Binary < Symlinked
  def link(command: nil, **options)
  super(command:, **options)

diff --git a/Library/Homebrew/cask/artifact/colorpicker.rb b/Library/Homebrew/cask/artifact/colorpicker.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `colorpicker` stanza.
- #
- # @api private
  class Colorpicker < Moved
  end
  end

diff --git a/Library/Homebrew/cask/artifact/dictionary.rb b/Library/Homebrew/cask/artifact/dictionary.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `dictionary` stanza.
- #
- # @api private
  class Dictionary < Moved
  end
  end

diff --git a/Library/Homebrew/cask/artifact/font.rb b/Library/Homebrew/cask/artifact/font.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `font` stanza.
- #
- # @api private
  class Font < Moved
  end
  end

diff --git a/Library/Homebrew/cask/artifact/input_method.rb b/Library/Homebrew/cask/artifact/input_method.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `input_method` stanza.
- #
- # @api private
  class InputMethod < Moved
  end
  end

diff --git a/Library/Homebrew/cask/artifact/installer.rb b/Library/Homebrew/cask/artifact/installer.rb
@@ -7,8 +7,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `installer` stanza.
- #
- # @api private
  class Installer < AbstractArtifact
  VALID_KEYS = Set.new([
  :manual,

diff --git a/Library/Homebrew/cask/artifact/internet_plugin.rb b/Library/Homebrew/cask/artifact/internet_plugin.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `internet_plugin` stanza.
- #
- # @api private
  class InternetPlugin < Moved
  end
  end

diff --git a/Library/Homebrew/cask/artifact/keyboard_layout.rb b/Library/Homebrew/cask/artifact/keyboard_layout.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `keyboard_layout` stanza.
- #
- # @api private
  class KeyboardLayout < Moved
  def install_phase(**options)
  super(**options)

diff --git a/Library/Homebrew/cask/artifact/manpage.rb b/Library/Homebrew/cask/artifact/manpage.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `manpage` stanza.
- #
- # @api private
  class Manpage < Symlinked
  attr_reader :section
 

diff --git a/Library/Homebrew/cask/artifact/mdimporter.rb b/Library/Homebrew/cask/artifact/mdimporter.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `mdimporter` stanza.
- #
- # @api private
  class Mdimporter < Moved
  sig { returns(String) }
  def self.english_name

diff --git a/Library/Homebrew/cask/artifact/moved.rb b/Library/Homebrew/cask/artifact/moved.rb
@@ -7,8 +7,6 @@
 module Cask
  module Artifact
  # Superclass for all artifacts that are installed by moving them to the target location.
- #
- # @api private
  class Moved < Relocated
  sig { returns(String) }
  def self.english_description

diff --git a/Library/Homebrew/cask/artifact/pkg.rb b/Library/Homebrew/cask/artifact/pkg.rb
@@ -10,8 +10,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `pkg` stanza.
- #
- # @api private
  class Pkg < AbstractArtifact
  attr_reader :path, :stanza_options
 

diff --git a/Library/Homebrew/cask/artifact/postflight_block.rb b/Library/Homebrew/cask/artifact/postflight_block.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `postflight` stanza.
- #
- # @api private
  class PostflightBlock < AbstractFlightBlock
  end
  end

diff --git a/Library/Homebrew/cask/artifact/preflight_block.rb b/Library/Homebrew/cask/artifact/preflight_block.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `preflight` stanza.
- #
- # @api private
  class PreflightBlock < AbstractFlightBlock
  end
  end

diff --git a/Library/Homebrew/cask/artifact/prefpane.rb b/Library/Homebrew/cask/artifact/prefpane.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `prefpane` stanza.
- #
- # @api private
  class Prefpane < Moved
  sig { returns(String) }
  def self.english_name

diff --git a/Library/Homebrew/cask/artifact/qlplugin.rb b/Library/Homebrew/cask/artifact/qlplugin.rb
@@ -6,8 +6,6 @@
 module Cask
  module Artifact
  # Artifact corresponding to the `qlplugin` stanza.
- #
- # @api private
  class Qlplugin < Moved
  sig { returns(String) }
  def self.english_name

diff --git a/Library/Homebrew/cask/artifact/relocated.rb b/Library/Homebrew/cask/artifact/relocated.rb
@@ -7,8 +7,6 @@
 module Cask
  module Artifact
  # Superclass for all artifacts which have a source and a target location.
- #
- # @api private
  class Relocated < AbstractArtifact
  def self.from_args(cask, *args)
  source_string, target_hash = args