diff --git a/Library/Homebrew/.yardopts b/Library/Homebrew/.yardopts index b90bbe7b213608..4bb4553c05ef6a 100644 --- 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 index 533593a96f4894..d8c898284faaa4 100644 --- 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 index 2fb76df526091c..429e20215e7e51 100644 --- 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 index 16759a1b562e9f..1cb1cecccba87c 100644 --- 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 index 2599bb40f3d5c6..abb6ec60204744 100644 --- 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,7 +189,6 @@ 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? @@ -199,7 +196,6 @@ def self.with_no_api_env(&block) 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 index fb5ddd7b44834b..da1803f8880068 100644 --- 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 index d70f6da2e17d9c..8d518c4406bb13 100644 --- 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 index 8dee0067ac6fd9..28f8068dee75b4 100644 --- a/Library/Homebrew/api/download.rb +++ b/Library/Homebrew/api/download.rb @@ -5,7 +5,6 @@ module Homebrew module API - # @api private class DownloadStrategy < CurlDownloadStrategy sig { override.returns(Pathname) } def symlink_location @@ -13,7 +12,6 @@ def symlink_location end end - # @api private class Download < Downloadable sig { params( diff --git a/Library/Homebrew/api/formula.rb b/Library/Homebrew/api/formula.rb index 5cda1457537fd0..e14866fefb4f99 100644 --- 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 index 9795c2e5af9a18..bdcd05d4f0925e 100644 --- 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 index e8427cb5c07a45..a07db8e88bfc24 100644 --- 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 index 10149e805a7d37..75f39c3193f166 100644 --- 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 index 7b7636ef1f4809..cc47324e32f355 100644 --- 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 index 4f2f017c97eea1..7592277120d048 100644 --- 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 index 06095d0b79133e..eab26b9f4334f3 100644 --- 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 index e13d9cc542afd3..e722d0bc0ff920 100644 --- 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 index eccdb10cab178a..5c8c4daec7b346 100644 --- 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 index 8cd40e7fe4e10a..4ed93fe16a8ba3 100644 --- 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 index c2ec38df445448..c4775ab3230337 100644 --- 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 index 9472fec95e7a3b..f28fa816c05dbd 100644 --- 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 index 1fe7cf108fa527..0a8b71eaa83106 100644 --- 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 index 16bbfe84248324..c28355025db98d 100644 --- 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 index 3743b70b21a578..a0d1bc7b5fe35a 100644 --- 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 index 50749b2bdd81b7..a247c0949e9a31 100644 --- 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 index caa2fcc7ba3ce4..2902156de6e1b9 100644 --- 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 index 79b3acaadf8753..347efba7d5e225 100644 --- 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 index 040045c80302b1..3a746b17cc8595 100644 --- 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 index 73c655a52bc345..a603b142000378 100644 --- 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 index 608279d2e21bbf..6b5364af14b9e5 100644 --- 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 index 2c085154dec1e7..de56dee06e95e6 100644 --- 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 index 27419fa7c289f8..ae0327f40f4ec9 100644 --- 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 index 22f17091a1844c..b6fe5c893f975b 100644 --- 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 index 0df431932fe1ef..313832b61f0f58 100644 --- 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 index 00d170fda7ce00..fb0e7b5efc2e6e 100644 --- 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 index 0b7f21c8ecd98c..d2845590356e25 100644 --- 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 index 04483f3170914b..a397234538424e 100644 --- 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 index bd95a3602ab689..f38164ff1c5d29 100644 --- 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 index 345699031dcdd1..5a66fd5cc80d7c 100644 --- 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 diff --git a/Library/Homebrew/cask/artifact/screen_saver.rb b/Library/Homebrew/cask/artifact/screen_saver.rb index c52e0361da015e..cc9cd6249fdcb6 100644 --- a/Library/Homebrew/cask/artifact/screen_saver.rb +++ b/Library/Homebrew/cask/artifact/screen_saver.rb @@ -6,8 +6,6 @@ module Cask module Artifact # Artifact corresponding to the `screen_saver` stanza. - # - # @api private class ScreenSaver < Moved end end diff --git a/Library/Homebrew/cask/artifact/service.rb b/Library/Homebrew/cask/artifact/service.rb index 901cb5ac07900b..032fd78788e54c 100644 --- a/Library/Homebrew/cask/artifact/service.rb +++ b/Library/Homebrew/cask/artifact/service.rb @@ -6,8 +6,6 @@ module Cask module Artifact # Artifact corresponding to the `service` stanza. - # - # @api private class Service < Moved end end diff --git a/Library/Homebrew/cask/artifact/stage_only.rb b/Library/Homebrew/cask/artifact/stage_only.rb index 41f23e0c1180ef..1f4b12be9e89ec 100644 --- a/Library/Homebrew/cask/artifact/stage_only.rb +++ b/Library/Homebrew/cask/artifact/stage_only.rb @@ -6,8 +6,6 @@ module Cask module Artifact # Artifact corresponding to the `stage_only` stanza. - # - # @api private class StageOnly < AbstractArtifact def self.from_args(cask, *args, **kwargs) if (args != [true] && args != ["true"]) || kwargs.present? diff --git a/Library/Homebrew/cask/artifact/suite.rb b/Library/Homebrew/cask/artifact/suite.rb index 6d7a2e3ccfd7dd..cc49c85b160580 100644 --- a/Library/Homebrew/cask/artifact/suite.rb +++ b/Library/Homebrew/cask/artifact/suite.rb @@ -6,8 +6,6 @@ module Cask module Artifact # Artifact corresponding to the `suite` stanza. - # - # @api private class Suite < Moved sig { returns(String) } def self.english_name diff --git a/Library/Homebrew/cask/artifact/symlinked.rb b/Library/Homebrew/cask/artifact/symlinked.rb index 1f5199d8876229..1de7e715ddb358 100644 --- a/Library/Homebrew/cask/artifact/symlinked.rb +++ b/Library/Homebrew/cask/artifact/symlinked.rb @@ -6,8 +6,6 @@ module Cask module Artifact # Superclass for all artifacts which are installed by symlinking them to the target location. - # - # @api private class Symlinked < Relocated sig { returns(String) } def self.link_type_english_name diff --git a/Library/Homebrew/cask/artifact/uninstall.rb b/Library/Homebrew/cask/artifact/uninstall.rb index 4b83e183252a76..cbb3b9cd78ddff 100644 --- a/Library/Homebrew/cask/artifact/uninstall.rb +++ b/Library/Homebrew/cask/artifact/uninstall.rb @@ -8,8 +8,6 @@ module Cask module Artifact # Artifact corresponding to the `uninstall` stanza. - # - # @api private class Uninstall < AbstractUninstall def uninstall_phase(upgrade: false, reinstall: false, **options) filtered_directives = ORDERED_DIRECTIVES.filter do |directive_sym| diff --git a/Library/Homebrew/cask/artifact/vst3_plugin.rb b/Library/Homebrew/cask/artifact/vst3_plugin.rb index 313c09cb95665e..f59701de59e0dd 100644 --- a/Library/Homebrew/cask/artifact/vst3_plugin.rb +++ b/Library/Homebrew/cask/artifact/vst3_plugin.rb @@ -6,8 +6,6 @@ module Cask module Artifact # Artifact corresponding to the `vst3_plugin` stanza. - # - # @api private class Vst3Plugin < Moved sig { returns(String) } def self.english_name diff --git a/Library/Homebrew/cask/artifact/vst_plugin.rb b/Library/Homebrew/cask/artifact/vst_plugin.rb index d2cdca6073e13d..cd330cc840fd16 100644 --- a/Library/Homebrew/cask/artifact/vst_plugin.rb +++ b/Library/Homebrew/cask/artifact/vst_plugin.rb @@ -6,8 +6,6 @@ module Cask module Artifact # Artifact corresponding to the `vst_plugin` stanza. - # - # @api private class VstPlugin < Moved sig { returns(String) } def self.english_name diff --git a/Library/Homebrew/cask/artifact/zap.rb b/Library/Homebrew/cask/artifact/zap.rb index eadc014618ea61..052149986a0b28 100644 --- a/Library/Homebrew/cask/artifact/zap.rb +++ b/Library/Homebrew/cask/artifact/zap.rb @@ -6,8 +6,6 @@ module Cask module Artifact # Artifact corresponding to the `zap` stanza. - # - # @api private class Zap < AbstractUninstall def zap_phase(**options) dispatch_uninstall_directives(**options) diff --git a/Library/Homebrew/cask/artifact_set.rb b/Library/Homebrew/cask/artifact_set.rb index b92d1eeaf9ea02..e3d45a9178bf8b 100644 --- a/Library/Homebrew/cask/artifact_set.rb +++ b/Library/Homebrew/cask/artifact_set.rb @@ -5,8 +5,6 @@ module Cask # Sorted set containing all cask artifacts. - # - # @api private class ArtifactSet < ::Set def each(&block) return enum_for(T.must(__method__)) { size } unless block diff --git a/Library/Homebrew/cask/audit.rb b/Library/Homebrew/cask/audit.rb index f2805902ef0f6a..067e775c9c31c0 100644 --- a/Library/Homebrew/cask/audit.rb +++ b/Library/Homebrew/cask/audit.rb @@ -14,8 +14,6 @@ module Cask # Audit a cask for various problems. - # - # @api private class Audit include SystemCommand::Mixin include ::Utils::Curl diff --git a/Library/Homebrew/cask/auditor.rb b/Library/Homebrew/cask/auditor.rb index 1485429020c7e4..7b5424e8f1931e 100644 --- a/Library/Homebrew/cask/auditor.rb +++ b/Library/Homebrew/cask/auditor.rb @@ -5,8 +5,6 @@ module Cask # Helper class for auditing all available languages of a cask. - # - # @api private class Auditor def self.audit(cask, **options) new(cask, **options).audit diff --git a/Library/Homebrew/cask/cache.rb b/Library/Homebrew/cask/cache.rb index d515d9d7a4a41c..9735e4789d8138 100644 --- a/Library/Homebrew/cask/cache.rb +++ b/Library/Homebrew/cask/cache.rb @@ -3,8 +3,6 @@ module Cask # Helper functions for the cask cache. - # - # @api private module Cache sig { returns(Pathname) } def self.path diff --git a/Library/Homebrew/cask/cask.rb b/Library/Homebrew/cask/cask.rb index 1b4a5309d04f3a..570feed456888a 100644 --- a/Library/Homebrew/cask/cask.rb +++ b/Library/Homebrew/cask/cask.rb @@ -12,8 +12,6 @@ module Cask # An instance of a cask. - # - # @api private class Cask extend Forwardable extend Attrable @@ -25,7 +23,6 @@ class Cask attr_predicate :loaded_from_api? - # @api private def self.all(eval_all: false) if !eval_all && !Homebrew::EnvConfig.eval_all? raise ArgumentError, "Cask::Cask#all cannot be used without `--eval-all` or HOMEBREW_EVAL_ALL" diff --git a/Library/Homebrew/cask/cask_loader.rb b/Library/Homebrew/cask/cask_loader.rb index 5f6aeaba377bb9..b92b06e38f53a9 100644 --- a/Library/Homebrew/cask/cask_loader.rb +++ b/Library/Homebrew/cask/cask_loader.rb @@ -9,8 +9,6 @@ module Cask # Loads a cask from various sources. - # - # @api private module CaskLoader extend Context diff --git a/Library/Homebrew/cask/caskroom.rb b/Library/Homebrew/cask/caskroom.rb index d83c53804a9816..9cb5ebd4576a53 100644 --- a/Library/Homebrew/cask/caskroom.rb +++ b/Library/Homebrew/cask/caskroom.rb @@ -5,8 +5,6 @@ module Cask # Helper functions for interacting with the `Caskroom` directory. - # - # @api private module Caskroom sig { returns(Pathname) } def self.path diff --git a/Library/Homebrew/cask/config.rb b/Library/Homebrew/cask/config.rb index 37854d8ec59ecf..5ceb41c89430ca 100644 --- a/Library/Homebrew/cask/config.rb +++ b/Library/Homebrew/cask/config.rb @@ -9,8 +9,6 @@ module Cask # Configuration for installing casks. - # - # @api private class Config DEFAULT_DIRS = { appdir: "/Applications", diff --git a/Library/Homebrew/cask/denylist.rb b/Library/Homebrew/cask/denylist.rb index 7afbcb46b1992e..d65584862e8cf8 100644 --- a/Library/Homebrew/cask/denylist.rb +++ b/Library/Homebrew/cask/denylist.rb @@ -3,8 +3,6 @@ module Cask # List of casks which are not allowed in official taps. - # - # @api private module Denylist sig { params(name: String).returns(T.nilable(String)) } def self.reason(name) diff --git a/Library/Homebrew/cask/download.rb b/Library/Homebrew/cask/download.rb index 047def35b189aa..cf71a16fa2766f 100644 --- a/Library/Homebrew/cask/download.rb +++ b/Library/Homebrew/cask/download.rb @@ -8,8 +8,6 @@ module Cask # A download corresponding to a {Cask}. - # - # @api private class Download < ::Downloadable include Context diff --git a/Library/Homebrew/cask/dsl.rb b/Library/Homebrew/cask/dsl.rb index e70b07f0205dad..24424f3f70f519 100644 --- a/Library/Homebrew/cask/dsl.rb +++ b/Library/Homebrew/cask/dsl.rb @@ -30,8 +30,6 @@ module Cask # Class representing the domain-specific language used for casks. - # - # @api private class DSL ORDINARY_ARTIFACT_CLASSES = [ Artifact::Installer, diff --git a/Library/Homebrew/cask/dsl/base.rb b/Library/Homebrew/cask/dsl/base.rb index 9a529b6d67de44..b849665a4092de 100644 --- a/Library/Homebrew/cask/dsl/base.rb +++ b/Library/Homebrew/cask/dsl/base.rb @@ -7,8 +7,6 @@ module Cask class DSL # Superclass for all stanzas which take a block. - # - # @api private class Base extend Forwardable diff --git a/Library/Homebrew/cask/dsl/caveats.rb b/Library/Homebrew/cask/dsl/caveats.rb index 356b9731ac3d20..c8a019a95cc923 100644 --- a/Library/Homebrew/cask/dsl/caveats.rb +++ b/Library/Homebrew/cask/dsl/caveats.rb @@ -14,8 +14,6 @@ class DSL # The return value of the last method in the block is also sent # to the output by the caller, but that feature is only for the # convenience of cask authors. - # - # @api private class Caveats < Base extend Attrable diff --git a/Library/Homebrew/cask/dsl/conflicts_with.rb b/Library/Homebrew/cask/dsl/conflicts_with.rb index 1b177198fd378c..c4a43116c499cc 100644 --- a/Library/Homebrew/cask/dsl/conflicts_with.rb +++ b/Library/Homebrew/cask/dsl/conflicts_with.rb @@ -7,8 +7,6 @@ module Cask class DSL # Class corresponding to the `conflicts_with` stanza. - # - # @api private class ConflictsWith < SimpleDelegator VALID_KEYS = [ :formula, diff --git a/Library/Homebrew/cask/dsl/container.rb b/Library/Homebrew/cask/dsl/container.rb index 7f3d970892edd0..907be47e4a7467 100644 --- a/Library/Homebrew/cask/dsl/container.rb +++ b/Library/Homebrew/cask/dsl/container.rb @@ -6,8 +6,6 @@ module Cask class DSL # Class corresponding to the `container` stanza. - # - # @api private class Container attr_accessor :nested, :type diff --git a/Library/Homebrew/cask/dsl/depends_on.rb b/Library/Homebrew/cask/dsl/depends_on.rb index e56faf089398a8..31ff402d554297 100644 --- a/Library/Homebrew/cask/dsl/depends_on.rb +++ b/Library/Homebrew/cask/dsl/depends_on.rb @@ -8,8 +8,6 @@ module Cask class DSL # Class corresponding to the `depends_on` stanza. - # - # @api private class DependsOn < SimpleDelegator VALID_KEYS = Set.new([ :formula, diff --git a/Library/Homebrew/cask/dsl/postflight.rb b/Library/Homebrew/cask/dsl/postflight.rb index 5231502325ba2b..3ceabd9cab3052 100644 --- a/Library/Homebrew/cask/dsl/postflight.rb +++ b/Library/Homebrew/cask/dsl/postflight.rb @@ -6,8 +6,6 @@ module Cask class DSL # Class corresponding to the `postflight` stanza. - # - # @api private class Postflight < Base include Staged diff --git a/Library/Homebrew/cask/dsl/preflight.rb b/Library/Homebrew/cask/dsl/preflight.rb index 79d2a63ba8556e..abaf1fb9751c32 100644 --- a/Library/Homebrew/cask/dsl/preflight.rb +++ b/Library/Homebrew/cask/dsl/preflight.rb @@ -6,8 +6,6 @@ module Cask class DSL # Class corresponding to the `preflight` stanza. - # - # @api private class Preflight < Base include Staged end diff --git a/Library/Homebrew/cask/dsl/uninstall_postflight.rb b/Library/Homebrew/cask/dsl/uninstall_postflight.rb index 9dc523b05d0a04..1a3e38e86887a7 100644 --- a/Library/Homebrew/cask/dsl/uninstall_postflight.rb +++ b/Library/Homebrew/cask/dsl/uninstall_postflight.rb @@ -4,8 +4,6 @@ module Cask class DSL # Class corresponding to the `uninstall_postflight` stanza. - # - # @api private class UninstallPostflight < Base end end diff --git a/Library/Homebrew/cask/dsl/uninstall_preflight.rb b/Library/Homebrew/cask/dsl/uninstall_preflight.rb index d35da3f51fa70a..5280e638bdb77e 100644 --- a/Library/Homebrew/cask/dsl/uninstall_preflight.rb +++ b/Library/Homebrew/cask/dsl/uninstall_preflight.rb @@ -6,8 +6,6 @@ module Cask class DSL # Class corresponding to the `uninstall_preflight` stanza. - # - # @api private class UninstallPreflight < Base include Staged end diff --git a/Library/Homebrew/cask/dsl/version.rb b/Library/Homebrew/cask/dsl/version.rb index 3b1887c0cda1b1..853a4f191ce7ed 100644 --- a/Library/Homebrew/cask/dsl/version.rb +++ b/Library/Homebrew/cask/dsl/version.rb @@ -4,8 +4,6 @@ module Cask class DSL # Class corresponding to the `version` stanza. - # - # @api private class Version < ::String DIVIDERS = { "." => :dots, diff --git a/Library/Homebrew/cask/exceptions.rb b/Library/Homebrew/cask/exceptions.rb index 8ec351cb59587a..aa4e91863dd930 100644 --- a/Library/Homebrew/cask/exceptions.rb +++ b/Library/Homebrew/cask/exceptions.rb @@ -3,13 +3,9 @@ module Cask # General cask error. - # - # @api private class CaskError < RuntimeError; end # Cask error containing multiple other errors. - # - # @api private class MultipleCaskErrors < CaskError def initialize(errors) super() @@ -27,8 +23,6 @@ def to_s end # Abstract cask error containing a cask token. - # - # @api private class AbstractCaskErrorWithToken < CaskError sig { returns(String) } attr_reader :token @@ -45,8 +39,6 @@ def initialize(token, reason = nil) end # Error when a cask is not installed. - # - # @api private class CaskNotInstalledError < AbstractCaskErrorWithToken sig { returns(String) } def to_s @@ -55,8 +47,6 @@ def to_s end # Error when a cask cannot be installed. - # - # @api private class CaskCannotBeInstalledError < AbstractCaskErrorWithToken attr_reader :message @@ -72,8 +62,6 @@ def to_s end # Error when a cask conflicts with another cask. - # - # @api private class CaskConflictError < AbstractCaskErrorWithToken attr_reader :conflicting_cask @@ -89,8 +77,6 @@ def to_s end # Error when a cask is not available. - # - # @api private class CaskUnavailableError < AbstractCaskErrorWithToken sig { returns(String) } def to_s @@ -99,8 +85,6 @@ def to_s end # Error when a cask is unreadable. - # - # @api private class CaskUnreadableError < CaskUnavailableError sig { returns(String) } def to_s @@ -109,8 +93,6 @@ def to_s end # Error when a cask in a specific tap is not available. - # - # @api private class TapCaskUnavailableError < CaskUnavailableError attr_reader :tap @@ -128,8 +110,6 @@ def to_s end # Error when a cask with the same name is found in multiple taps. - # - # @api private class TapCaskAmbiguityError < CaskError sig { returns(String) } attr_reader :token @@ -154,8 +134,6 @@ def initialize(token, loaders) end # Error when a cask already exists. - # - # @api private class CaskAlreadyCreatedError < AbstractCaskErrorWithToken sig { returns(String) } def to_s @@ -164,8 +142,6 @@ def to_s end # Error when there is a cyclic cask dependency. - # - # @api private class CaskCyclicDependencyError < AbstractCaskErrorWithToken sig { returns(String) } def to_s @@ -174,8 +150,6 @@ def to_s end # Error when a cask depends on itself. - # - # @api private class CaskSelfReferencingDependencyError < CaskCyclicDependencyError sig { returns(String) } def to_s @@ -184,8 +158,6 @@ def to_s end # Error when no cask is specified. - # - # @api private class CaskUnspecifiedError < CaskError sig { returns(String) } def to_s @@ -194,8 +166,6 @@ def to_s end # Error when a cask is invalid. - # - # @api private class CaskInvalidError < AbstractCaskErrorWithToken sig { returns(String) } def to_s @@ -204,8 +174,6 @@ def to_s end # Error when a cask token does not match the file name. - # - # @api private class CaskTokenMismatchError < CaskInvalidError def initialize(token, header_token) super(token, "Token '#{header_token}' in header line does not match the file name.") @@ -213,8 +181,6 @@ def initialize(token, header_token) end # Error during quarantining of a file. - # - # @api private class CaskQuarantineError < CaskError attr_reader :path, :reason @@ -240,8 +206,6 @@ def to_s end # Error while propagating quarantine information to subdirectories. - # - # @api private class CaskQuarantinePropagationError < CaskQuarantineError sig { returns(String) } def to_s @@ -258,8 +222,6 @@ def to_s end # Error while removing quarantine information. - # - # @api private class CaskQuarantineReleaseError < CaskQuarantineError sig { returns(String) } def to_s diff --git a/Library/Homebrew/cask/info.rb b/Library/Homebrew/cask/info.rb index 8864e4f44b513c..18ccf66894881b 100644 --- a/Library/Homebrew/cask/info.rb +++ b/Library/Homebrew/cask/info.rb @@ -4,8 +4,6 @@ require "json" module Cask - # - # @api private class Info def self.get_info(cask) require "cask/installer" diff --git a/Library/Homebrew/cask/installer.rb b/Library/Homebrew/cask/installer.rb index 8148e50d357ea3..b7d4309ca92813 100644 --- a/Library/Homebrew/cask/installer.rb +++ b/Library/Homebrew/cask/installer.rb @@ -15,8 +15,6 @@ module Cask # Installer for a {Cask}. - # - # @api private class Installer extend Attrable diff --git a/Library/Homebrew/cask/list.rb b/Library/Homebrew/cask/list.rb index 82d0ddf2ad1c8a..2333ae620e8c64 100644 --- a/Library/Homebrew/cask/list.rb +++ b/Library/Homebrew/cask/list.rb @@ -4,7 +4,6 @@ require "cask/artifact/relocated" module Cask - # @api private class List def self.list_casks(*casks, one: false, full_name: false, versions: false) output = if casks.any? diff --git a/Library/Homebrew/cask/metadata.rb b/Library/Homebrew/cask/metadata.rb index c7c664808499c1..eabb22275ac3e2 100644 --- a/Library/Homebrew/cask/metadata.rb +++ b/Library/Homebrew/cask/metadata.rb @@ -3,8 +3,6 @@ module Cask # Helper module for reading and writing cask metadata. - # - # @api private module Metadata METADATA_SUBDIR = ".metadata" TIMESTAMP_FORMAT = "%Y%m%d%H%M%S.%L" diff --git a/Library/Homebrew/cask/pkg.rb b/Library/Homebrew/cask/pkg.rb index 8d204251d72c70..0540d8427e196b 100644 --- a/Library/Homebrew/cask/pkg.rb +++ b/Library/Homebrew/cask/pkg.rb @@ -5,8 +5,6 @@ module Cask # Helper class for uninstalling `.pkg` installers. - # - # @api private class Pkg sig { params(regexp: String, command: T.class_of(SystemCommand)).returns(T::Array[Pkg]) } def self.all_matching(regexp, command) diff --git a/Library/Homebrew/cask/quarantine.rb b/Library/Homebrew/cask/quarantine.rb index 2d5fd2589201ff..2fdd99c98ff753 100644 --- a/Library/Homebrew/cask/quarantine.rb +++ b/Library/Homebrew/cask/quarantine.rb @@ -7,8 +7,6 @@ module Cask # Helper module for quarantining files. - # - # @api private module Quarantine extend SystemCommand::Mixin diff --git a/Library/Homebrew/cask/reinstall.rb b/Library/Homebrew/cask/reinstall.rb index 1a4cf728d8e9b3..7fa966fc1e8487 100644 --- a/Library/Homebrew/cask/reinstall.rb +++ b/Library/Homebrew/cask/reinstall.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true module Cask - # - # @api private class Reinstall def self.reinstall_casks( *casks, diff --git a/Library/Homebrew/cask/staged.rb b/Library/Homebrew/cask/staged.rb index 74df26ec2165c9..613c3e42c16b0f 100644 --- a/Library/Homebrew/cask/staged.rb +++ b/Library/Homebrew/cask/staged.rb @@ -5,8 +5,6 @@ module Cask # Helper functions for staged casks. - # - # @api private module Staged # FIXME: Enable cop again when https://github.com/sorbet/sorbet/issues/3532 is fixed. # rubocop:disable Style/MutableConstant diff --git a/Library/Homebrew/cask/uninstall.rb b/Library/Homebrew/cask/uninstall.rb index be1da477a66ccd..bd17ff7bbfaca7 100644 --- a/Library/Homebrew/cask/uninstall.rb +++ b/Library/Homebrew/cask/uninstall.rb @@ -2,7 +2,6 @@ # frozen_string_literal: true module Cask - # @api private class Uninstall def self.uninstall_casks(*casks, binaries: nil, force: false, verbose: false) require "cask/installer" diff --git a/Library/Homebrew/cask/upgrade.rb b/Library/Homebrew/cask/upgrade.rb index 558109b6dfec9c..f0dc11178dcc31 100644 --- a/Library/Homebrew/cask/upgrade.rb +++ b/Library/Homebrew/cask/upgrade.rb @@ -5,7 +5,6 @@ require "cask/config" module Cask - # @api private class Upgrade sig { params( diff --git a/Library/Homebrew/cask/url.rb b/Library/Homebrew/cask/url.rb index 792ee814a2adac..4afd7463970a37 100644 --- a/Library/Homebrew/cask/url.rb +++ b/Library/Homebrew/cask/url.rb @@ -6,10 +6,7 @@ module Cask # Class corresponding to the `url` stanza. - # - # @api private class URL < Delegator - # @api private class DSL attr_reader :uri, :specs, :verified, :using, @@ -79,7 +76,6 @@ def initialize( end end - # @api private class BlockDSL # To access URL associated with page contents. module PageWithURL diff --git a/Library/Homebrew/cask/utils.rb b/Library/Homebrew/cask/utils.rb index 4f8f2afffaec99..8a8cddfbcc1954 100644 --- a/Library/Homebrew/cask/utils.rb +++ b/Library/Homebrew/cask/utils.rb @@ -8,8 +8,6 @@ module Cask # Helper functions for various cask operations. - # - # @api private module Utils def self.gain_permissions_mkpath(path, command: SystemCommand) dir = path.ascend.find(&:directory?) diff --git a/Library/Homebrew/caveats.rb b/Library/Homebrew/caveats.rb index c2fe663de65197..49af60b28240cf 100644 --- a/Library/Homebrew/caveats.rb +++ b/Library/Homebrew/caveats.rb @@ -5,8 +5,6 @@ require "utils/service" # A formula's caveats. -# -# @api private class Caveats extend Forwardable diff --git a/Library/Homebrew/checksum.rb b/Library/Homebrew/checksum.rb index 30d0d2f22e749e..e19998d3844935 100644 --- a/Library/Homebrew/checksum.rb +++ b/Library/Homebrew/checksum.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true # A formula's checksum. -# -# @api private class Checksum extend Forwardable diff --git a/Library/Homebrew/cleanup.rb b/Library/Homebrew/cleanup.rb index d3176c26ca61c8..c5b2a437d7a675 100644 --- a/Library/Homebrew/cleanup.rb +++ b/Library/Homebrew/cleanup.rb @@ -10,8 +10,6 @@ module Homebrew # Helper class for cleaning up the Homebrew cache. - # - # @api private class Cleanup CLEANUP_DEFAULT_DAYS = Homebrew::EnvConfig.cleanup_periodic_full_days.to_i.freeze private_constant :CLEANUP_DEFAULT_DAYS diff --git a/Library/Homebrew/cli/named_args.rb b/Library/Homebrew/cli/named_args.rb index da8118f2ce5527..5bb1e5441fb907 100644 --- a/Library/Homebrew/cli/named_args.rb +++ b/Library/Homebrew/cli/named_args.rb @@ -8,8 +8,6 @@ module Homebrew module CLI # Helper class for loading formulae/casks from named arguments. - # - # @api private class NamedArgs < Array sig { params( diff --git a/Library/Homebrew/commands.rb b/Library/Homebrew/commands.rb index d57563a27d3a7a..3a31f7466c5035 100644 --- a/Library/Homebrew/commands.rb +++ b/Library/Homebrew/commands.rb @@ -4,8 +4,6 @@ require "completions" # Helper functions for commands. -# -# @api private module Commands HOMEBREW_CMD_PATH = (HOMEBREW_LIBRARY_PATH/"cmd").freeze HOMEBREW_DEV_CMD_PATH = (HOMEBREW_LIBRARY_PATH/"dev-cmd").freeze diff --git a/Library/Homebrew/compilers.rb b/Library/Homebrew/compilers.rb index 9133c6fa8f139c..20503c36d555bb 100644 --- a/Library/Homebrew/compilers.rb +++ b/Library/Homebrew/compilers.rb @@ -1,7 +1,6 @@ # typed: true # frozen_string_literal: true -# @private module CompilerConstants GNU_GCC_VERSIONS = %w[4.9 5 6 7 8 9 10 11 12 13].freeze GNU_GCC_REGEXP = /^gcc-(4\.9|[5-9]|10|11|12|13)$/ @@ -16,8 +15,6 @@ module CompilerConstants end # Class for checking compiler compatibility for a formula. -# -# @api private class CompilerFailure attr_reader :type @@ -97,8 +94,6 @@ def gcc_major(version) end # Class for selecting a compiler for a formula. -# -# @api private class CompilerSelector include CompilerConstants diff --git a/Library/Homebrew/completions.rb b/Library/Homebrew/completions.rb index 60d50f155587dd..b1eafb3f10a64b 100644 --- a/Library/Homebrew/completions.rb +++ b/Library/Homebrew/completions.rb @@ -7,8 +7,6 @@ module Homebrew # Helper functions for generating shell completions. - # - # @api private module Completions Variables = Struct.new( :aliases, diff --git a/Library/Homebrew/context.rb b/Library/Homebrew/context.rb index d1f01c48deff2d..801f34faabd875 100644 --- a/Library/Homebrew/context.rb +++ b/Library/Homebrew/context.rb @@ -4,8 +4,6 @@ require "monitor" # Module for querying the current execution context. -# -# @api private module Context extend MonitorMixin diff --git a/Library/Homebrew/debrew.rb b/Library/Homebrew/debrew.rb index c465f5d22c8324..15d514e084b38a 100644 --- a/Library/Homebrew/debrew.rb +++ b/Library/Homebrew/debrew.rb @@ -6,8 +6,6 @@ require "ignorable" # Helper module for debugging formulae. -# -# @api private module Debrew extend Mutex_m diff --git a/Library/Homebrew/debrew/irb.rb b/Library/Homebrew/debrew/irb.rb index af3c358c9d3a41..ade8673e47dcb2 100644 --- a/Library/Homebrew/debrew/irb.rb +++ b/Library/Homebrew/debrew/irb.rb @@ -3,7 +3,6 @@ require "irb" -# @private module IRB def self.start_within(binding) unless @setup_done diff --git a/Library/Homebrew/dependable.rb b/Library/Homebrew/dependable.rb index 6e4819ed2200a0..570309d540696b 100644 --- a/Library/Homebrew/dependable.rb +++ b/Library/Homebrew/dependable.rb @@ -4,8 +4,6 @@ require "options" # Shared functions for classes which can be depended upon. -# -# @api private module Dependable # `:run` and `:linked` are no longer used but keep them here to avoid their # misuse in future. diff --git a/Library/Homebrew/dependencies.rb b/Library/Homebrew/dependencies.rb index 1e69bfecdf4875..6eec3de36e8e01 100644 --- a/Library/Homebrew/dependencies.rb +++ b/Library/Homebrew/dependencies.rb @@ -4,8 +4,6 @@ require "delegate" # A collection of dependencies. -# -# @api private class Dependencies < SimpleDelegator def initialize(*args) super(args) @@ -44,8 +42,6 @@ def inspect end # A collection of requirements. -# -# @api private class Requirements < SimpleDelegator def initialize(*args) super(Set.new(args)) diff --git a/Library/Homebrew/dependencies_helpers.rb b/Library/Homebrew/dependencies_helpers.rb index 0f0b6928a084c1..fa6b3b2b4bc072 100644 --- a/Library/Homebrew/dependencies_helpers.rb +++ b/Library/Homebrew/dependencies_helpers.rb @@ -4,8 +4,6 @@ require "cask_dependent" # Helper functions for dependencies. -# -# @api private module DependenciesHelpers def args_includes_ignores(args) includes = [:required?, :recommended?] # included by default diff --git a/Library/Homebrew/dependency.rb b/Library/Homebrew/dependency.rb index b11d2cff0a6e7a..9c97ea1d40c787 100644 --- a/Library/Homebrew/dependency.rb +++ b/Library/Homebrew/dependency.rb @@ -4,8 +4,6 @@ require "dependable" # A dependency on another Homebrew formula. -# -# @api private class Dependency extend Forwardable include Dependable diff --git a/Library/Homebrew/dependency_collector.rb b/Library/Homebrew/dependency_collector.rb index 713818655f5e8a..4d03ada7f81e91 100644 --- a/Library/Homebrew/dependency_collector.rb +++ b/Library/Homebrew/dependency_collector.rb @@ -158,7 +158,7 @@ def parse_string_spec(spec, tags) def parse_symbol_spec(spec, tags) # When modifying this list of supported requirements, consider - # whether Formulary::API_SUPPORTED_REQUIREMENTS should also be changed. + # whether `Formulary::API_SUPPORTED_REQUIREMENTS` should also be changed. case spec when :arch then ArchRequirement.new(tags) when :codesign then CodesignRequirement.new(tags) diff --git a/Library/Homebrew/deprecate_disable.rb b/Library/Homebrew/deprecate_disable.rb index fcd8081954c78d..36d69839c9bfd7 100644 --- a/Library/Homebrew/deprecate_disable.rb +++ b/Library/Homebrew/deprecate_disable.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true # Helper module for handling `disable!` and `deprecate!`. -# -# @api private module DeprecateDisable module_function diff --git a/Library/Homebrew/descriptions.rb b/Library/Homebrew/descriptions.rb index 80e9fa89df6cb2..309ff26cc95e1e 100644 --- a/Library/Homebrew/descriptions.rb +++ b/Library/Homebrew/descriptions.rb @@ -6,8 +6,6 @@ require "search" # Helper class for printing and searching descriptions. -# -# @api private class Descriptions # Given a regex, find all formulae whose specified fields contain a match. def self.search(string_or_regex, field, cache_store, eval_all = Homebrew::EnvConfig.eval_all?) diff --git a/Library/Homebrew/dev-cmd/rubydoc.rb b/Library/Homebrew/dev-cmd/rubydoc.rb new file mode 100644 index 00000000000000..eec4eddbfa8eb5 --- /dev/null +++ b/Library/Homebrew/dev-cmd/rubydoc.rb @@ -0,0 +1,41 @@ +# typed: true +# frozen_string_literal: true + +require "cli/parser" +require "formula" + +module Homebrew + module_function + + sig { returns(CLI::Parser) } + def rubydoc_args + Homebrew::CLI::Parser.new do + description <<~EOS + Generate Homebrew's RubyDoc documentation. + EOS + switch "--only-public", + description: "Only generate public API documentation." + switch "--open", + description: "Open generated documentation in a browser." + end + end + + sig { void } + def rubydoc + args = rubydoc_args.parse + + Homebrew.install_bundler_gems!(groups: ["doc"]) + + HOMEBREW_LIBRARY_PATH.cd do + 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 + + exec_browser "file://#{HOMEBREW_LIBRARY_PATH}/doc/index.html" if args.open? + end + end +end diff --git a/Library/Homebrew/development_tools.rb b/Library/Homebrew/development_tools.rb index b9976befff1222..3065d4f3f98b08 100644 --- a/Library/Homebrew/development_tools.rb +++ b/Library/Homebrew/development_tools.rb @@ -3,7 +3,6 @@ require "version" -# @private class DevelopmentTools class << self sig { params(tool: T.any(String, Symbol)).returns(T.nilable(Pathname)) } diff --git a/Library/Homebrew/diagnostic.rb b/Library/Homebrew/diagnostic.rb index 9792ed45f6f50c..a14d89d501f4a0 100644 --- a/Library/Homebrew/diagnostic.rb +++ b/Library/Homebrew/diagnostic.rb @@ -15,8 +15,6 @@ module Homebrew # Module containing diagnostic checks. - # - # @api private module Diagnostic def self.missing_deps(formulae, hide = nil) missing = {} diff --git a/Library/Homebrew/download_strategy.rb b/Library/Homebrew/download_strategy.rb index bc5cd52425bd9c..2252caeb6e74f5 100644 --- a/Library/Homebrew/download_strategy.rb +++ b/Library/Homebrew/download_strategy.rb @@ -23,8 +23,6 @@ class Mechanize; end require "github_packages" # @abstract Abstract superclass for all download strategies. -# -# @api private class AbstractDownloadStrategy extend Forwardable include FileUtils @@ -32,8 +30,6 @@ class AbstractDownloadStrategy include SystemCommand::Mixin # Extension for bottle downloads. - # - # @api private module Pourable def stage ohai "Pouring #{basename}" @@ -83,7 +79,6 @@ def quiet! # Disable any output during downloading. # # @deprecated - # @api private sig { void } def shutup! odeprecated "AbstractDownloadStrategy#shutup!", "AbstractDownloadStrategy#quiet!" @@ -188,8 +183,6 @@ def env end # @abstract Abstract superclass for all download strategies downloading from a version control system. -# -# @api private class VCSDownloadStrategy < AbstractDownloadStrategy REF_TYPES = [:tag, :branch, :revisions, :revision].freeze @@ -278,8 +271,6 @@ def extract_ref(specs) end # @abstract Abstract superclass for all download strategies downloading a single file. -# -# @api private class AbstractFileDownloadStrategy < AbstractDownloadStrategy # Path for storing an incomplete download while the download is still in progress. # @@ -716,8 +707,6 @@ def stage end # Strategy for extracting local binary packages. -# -# @api private class LocalBottleDownloadStrategy < AbstractFileDownloadStrategy def initialize(path) # rubocop:disable Lint/MissingSuper @cached_location = path @@ -1444,8 +1433,6 @@ def update(timeout: nil) end # Helper class for detecting a download strategy from a URL. -# -# @api private class DownloadStrategyDetector def self.detect(url, using = nil) if using.nil? diff --git a/Library/Homebrew/downloadable.rb b/Library/Homebrew/downloadable.rb index 629cc9867aa5b0..8c03630621f82b 100644 --- a/Library/Homebrew/downloadable.rb +++ b/Library/Homebrew/downloadable.rb @@ -4,7 +4,6 @@ require "url" require "checksum" -# @api private class Downloadable include Context extend T::Helpers diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb index c7eccd09e39787..73f046bda1fbc2 100644 --- a/Library/Homebrew/env_config.rb +++ b/Library/Homebrew/env_config.rb @@ -5,8 +5,6 @@ module Homebrew # Helper module for querying Homebrew-specific environment variables. - # - # @api private module EnvConfig module_function diff --git a/Library/Homebrew/exceptions.rb b/Library/Homebrew/exceptions.rb index 1094c7e517bf6a..9f96aea2808334 100644 --- a/Library/Homebrew/exceptions.rb +++ b/Library/Homebrew/exceptions.rb @@ -73,8 +73,6 @@ def initialize(formula, attr, value) class FormulaSpecificationError < StandardError; end # Raised when a deprecated method is used. -# -# @api private class MethodDeprecatedError < StandardError attr_accessor :issues_url end @@ -148,8 +146,6 @@ def to_s end # Shared methods for formula class errors. -# -# @api private module FormulaClassUnavailableErrorModule attr_reader :path, :class_name, :class_list @@ -192,8 +188,6 @@ def initialize(name, path, class_name, class_list) end # Shared methods for formula unreadable errors. -# -# @api private module FormulaUnreadableErrorModule attr_reader :formula_error diff --git a/Library/Homebrew/extend/ENV/std.rb b/Library/Homebrew/extend/ENV/std.rb index 19cec7ad88e50a..1f2130d9786673 100644 --- a/Library/Homebrew/extend/ENV/std.rb +++ b/Library/Homebrew/extend/ENV/std.rb @@ -4,14 +4,12 @@ require "hardware" require "extend/ENV/shared" -# @api private module Stdenv include SharedEnvExtension # @private SAFE_CFLAGS_FLAGS = "-w -pipe" - # @private sig { params( formula: T.nilable(Formula), @@ -72,6 +70,7 @@ def setup_build_environment(formula: nil, cc: nil, build_bottle: false, bottle_a end alias generic_setup_build_environment setup_build_environment + # @private sig { returns(T::Array[Pathname]) } def homebrew_extra_pkg_config_paths [] @@ -165,6 +164,8 @@ def replace_in_cflags(before, after) end # Convenience method to set all C compiler flags in one shot. + # + # @private sig { params(val: String).void } def define_cflags(val) CC_FLAG_VARS.each { |key| self[key] = val } diff --git a/Library/Homebrew/extend/ENV/super.rb b/Library/Homebrew/extend/ENV/super.rb index 6beeb4cb2f4081..5cfc4073183f9b 100644 --- a/Library/Homebrew/extend/ENV/super.rb +++ b/Library/Homebrew/extend/ENV/super.rb @@ -33,7 +33,6 @@ def self.shims_path HOMEBREW_SHIMS_PATH/"super" end - # @private sig { returns(T.nilable(Pathname)) } def self.bin; end @@ -162,6 +161,7 @@ def determine_path path.existing end + # @private sig { returns(T::Array[Pathname]) } def homebrew_extra_pkg_config_paths [] diff --git a/Library/Homebrew/extend/hash/keys.rb b/Library/Homebrew/extend/hash/keys.rb index caa742d3b2e037..06878a4ce0d514 100644 --- a/Library/Homebrew/extend/hash/keys.rb +++ b/Library/Homebrew/extend/hash/keys.rb @@ -2,17 +2,17 @@ # frozen_string_literal: true class Hash - # Validates all keys in a hash match *valid_keys, raising - # +ArgumentError+ on a mismatch. + # Validates all keys in a hash match `*valid_keys`, raising + # `ArgumentError` on a mismatch. # # 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 + # { 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 +28,10 @@ def assert_valid_keys(*valid_keys) # This includes the keys from the root hash and from all # nested hashes and arrays. # - # hash = { person: { name: 'Rob', age: '28' } } + # hash = { person: { name: 'Rob', age: '28' } } # - # hash.deep_transform_keys{ |key| key.to_s.upcase } - # # => {"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 +43,10 @@ def deep_transform_keys!(&block) = _deep_transform_keys_in_object!(self, &block) # This includes the keys from the root hash and from all # nested hashes and arrays. # - # hash = { person: { name: 'Rob', age: '28' } } + # hash = { person: { name: 'Rob', age: '28' } } # - # hash.deep_stringify_keys - # # => {"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. @@ -58,10 +58,10 @@ def deep_stringify_keys! = T.unsafe(self).deep_transform_keys!(&:to_s) # 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' } } + # hash = { 'person' => { 'name' => 'Rob', 'age' => '28' } } # - # hash.deep_symbolize_keys - # # => {: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 diff --git a/Library/Homebrew/extend/os/mac/development_tools.rb b/Library/Homebrew/extend/os/mac/development_tools.rb index df43d554bbfedd..d53f77a858a586 100644 --- a/Library/Homebrew/extend/os/mac/development_tools.rb +++ b/Library/Homebrew/extend/os/mac/development_tools.rb @@ -3,7 +3,6 @@ require "os/mac/xcode" -# @private class DevelopmentTools class << self alias generic_locate locate diff --git a/Library/Homebrew/extend/os/mac/extend/ENV/std.rb b/Library/Homebrew/extend/os/mac/extend/ENV/std.rb index 51e79be5060243..bbb76c7d8c28a0 100644 --- a/Library/Homebrew/extend/os/mac/extend/ENV/std.rb +++ b/Library/Homebrew/extend/os/mac/extend/ENV/std.rb @@ -2,10 +2,9 @@ # frozen_string_literal: true module Stdenv - # @private - undef homebrew_extra_pkg_config_paths + # @private def homebrew_extra_pkg_config_paths [Pathname("#{HOMEBREW_LIBRARY}/Homebrew/os/mac/pkgconfig/#{MacOS.version}")] end diff --git a/Library/Homebrew/extend/os/mac/extend/ENV/super.rb b/Library/Homebrew/extend/os/mac/extend/ENV/super.rb index bfcd39695e8520..923bb52b3bc18e 100644 --- a/Library/Homebrew/extend/os/mac/extend/ENV/super.rb +++ b/Library/Homebrew/extend/os/mac/extend/ENV/super.rb @@ -10,7 +10,6 @@ def shims_path undef bin - # @private def bin return unless DevelopmentTools.installed? diff --git a/Library/Homebrew/extend/pathname.rb b/Library/Homebrew/extend/pathname.rb index e7fd27f2b26330..dd0a8dbb1e4dcc 100644 --- a/Library/Homebrew/extend/pathname.rb +++ b/Library/Homebrew/extend/pathname.rb @@ -82,6 +82,8 @@ class Pathname include DiskUsageExtension # Moves a file from the original location to the {Pathname}'s. + # + # @api public sig { params(sources: T.any( Resource, Resource::Partial, String, Pathname, @@ -137,6 +139,8 @@ def install_p(src, new_basename) private :install_p # Creates symlinks to sources in this folder. + # + # @api public sig { params( sources: T.any(String, Pathname, T::Array[T.any(String, Pathname)], T::Hash[T.any(String, Pathname), String]), @@ -165,6 +169,8 @@ def install_symlink_p(src, new_basename) private :install_symlink_p # Only appends to a file that is already created. + # + # @api public sig { params(content: String, open_args: T.untyped).void } def append_lines(content, **open_args) raise "Cannot append file that doesn't exist: #{self}" unless exist? @@ -173,6 +179,8 @@ def append_lines(content, **open_args) end # @note This always overwrites. + # + # @api public sig { params(content: String).void } def atomic_write(content) old_stat = stat if exist? @@ -202,7 +210,6 @@ def atomic_write(content) end end - # @private def cp_path_sub(pattern, replacement) raise "#{self} does not exist" unless exist? @@ -223,6 +230,8 @@ def cp_path_sub(pattern, replacement) alias extname_old extname # Extended to support common double extensions. + # + # @api public sig { returns(String) } def extname basename = File.basename(self) @@ -240,6 +249,8 @@ def extname end # For filetypes we support, returns basename without extension. + # + # @api public sig { returns(String) } def stem File.basename(self, extname) @@ -248,7 +259,6 @@ def stem # I don't trust the children.length == 0 check particularly, not to mention # it is slow to enumerate the whole directory just to see if it is empty, # instead rely on good ol' libc and the filesystem - # @private sig { returns(T::Boolean) } def rmdir_if_possible rmdir @@ -264,14 +274,12 @@ def rmdir_if_possible false end - # @private sig { returns(Version) } def version require "version" Version.parse(basename) end - # @private sig { returns(T::Boolean) } def text_executable? /\A#!\s*\S+/.match?(open("r") { |f| f.read(1024) }) @@ -293,6 +301,9 @@ def verify_checksum(expected) alias to_str to_s + # Change to this directory, optionally executing the given block. + # + # @api public sig { type_parameters(:U).params( _block: T.proc.params(path: Pathname).returns(T.type_parameter(:U)), @@ -302,18 +313,19 @@ def cd(&_block) Dir.chdir(self) { yield self } end + # Get all sub-directories of this directory. + # + # @api public sig { returns(T::Array[Pathname]) } def subdirs children.select(&:directory?) end - # @private sig { returns(Pathname) } def resolved_path symlink? ? dirname.join(readlink) : self end - # @private sig { returns(T::Boolean) } def resolved_path_exists? link = readlink @@ -324,13 +336,11 @@ def resolved_path_exists? dirname.join(link).exist? end - # @private def make_relative_symlink(src) dirname.mkpath File.symlink(src.relative_path_from(dirname), self) end - # @private def ensure_writable saved_perms = nil unless writable? @@ -342,7 +352,6 @@ def ensure_writable chmod saved_perms if saved_perms end - # @private def which_install_info @which_install_info ||= if File.executable?("/usr/bin/install-info") @@ -352,12 +361,10 @@ def which_install_info end end - # @private def install_info quiet_system(which_install_info, "--quiet", to_s, "#{dirname}/dir") end - # @private def uninstall_info quiet_system(which_install_info, "--delete", "--quiet", to_s, "#{dirname}/dir") end @@ -494,7 +501,6 @@ def zipinfo require "extend/os/pathname" -# @private module ObserverPathnameExtension class << self include Context diff --git a/Library/Homebrew/fetch.rb b/Library/Homebrew/fetch.rb index 3aeaee8929eb18..587a17f4ed3867 100644 --- a/Library/Homebrew/fetch.rb +++ b/Library/Homebrew/fetch.rb @@ -2,7 +2,6 @@ # frozen_string_literal: true module Homebrew - # @api private module Fetch sig { params( diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index 5f83c4c7e10e70..e61a07c51c687f 100644 --- a/Library/Homebrew/formula.rb +++ b/Library/Homebrew/formula.rb @@ -104,14 +104,12 @@ class Formula # The {Tap} instance associated with this {Formula}. # If it's `nil`, then this formula is loaded from a path or URL. - # @private sig { returns(T.nilable(Tap)) } attr_reader :tap # The stable (and default) {SoftwareSpec} for this {Formula}. # This contains all the attributes (e.g. URL, checksum) that apply to the # stable version of this formula. - # @private sig { returns(T.nilable(SoftwareSpec)) } attr_reader :stable @@ -121,7 +119,6 @@ class Formula # commit in the version control system. # `nil` if there is no HEAD version. # @see #stable - # @private sig { returns(T.nilable(SoftwareSpec)) } attr_reader :head @@ -135,12 +132,10 @@ class Formula # A symbol to indicate currently active {SoftwareSpec}. # It's either :stable or :head # @see #active_spec - # @private sig { returns(Symbol) } attr_reader :active_spec_sym # most recent modified time for source files - # @private sig { returns(T.nilable(Time)) } attr_reader :source_modified_time @@ -167,13 +162,11 @@ class Formula # When installing a bottle (binary package) from a local path this will be # set to the full path to the bottle tarball. If not, it will be `nil`. - # @private sig { returns(T.nilable(Pathname)) } attr_accessor :local_bottle_path # When performing a build, test, or other loggable action, indicates which # log file location to use. - # @private sig { returns(T.nilable(String)) } attr_reader :active_log_type @@ -193,11 +186,9 @@ class Formula alias follow_installed_alias? follow_installed_alias # Whether or not to force the use of a bottle. - # @private sig { returns(T::Boolean) } attr_accessor :force_bottle - # @private sig { params(name: String, path: Pathname, spec: Symbol, alias_path: T.nilable(Pathname), tap: T.nilable(Tap), force_bottle: T::Boolean).void @@ -249,7 +240,6 @@ def initialize(name, path, spec, alias_path: nil, tap: nil, force_bottle: false) @oldname_locks = [] end - # @private def active_spec=(spec_sym) spec = send(spec_sym) raise FormulaSpecificationError, "#{spec_sym} spec is not available for #{full_name}" unless spec @@ -266,7 +256,6 @@ def active_spec=(spec_sym) Requirement.clear_cache end - # @private def build=(build_options) old_options = @build @build = build_options @@ -380,21 +369,18 @@ def full_installed_specified_name end # Is the currently active {SoftwareSpec} a {#stable} build? - # @private sig { returns(T::Boolean) } def stable? active_spec == stable end # Is the currently active {SoftwareSpec} a {#head} build? - # @private sig { returns(T::Boolean) } def head? active_spec == head end # Is this formula HEAD-only? - # @private sig { returns(T::Boolean) } def head_only? !!head && !stable @@ -409,14 +395,12 @@ def head_only? ] => :active_spec # The Bottle object for the currently active {SoftwareSpec}. - # @private sig { returns(T.nilable(Bottle)) } def bottle @bottle ||= Bottle.new(self, bottle_specification) if bottled? end # The Bottle object for given tag. - # @private sig { params(tag: T.nilable(Utils::Bottles::Tag)).returns(T.nilable(Bottle)) } def bottle_for_tag(tag = nil) Bottle.new(self, bottle_specification, tag) if bottled?(tag) @@ -434,7 +418,6 @@ def bottle_for_tag(tag = nil) # The homepage for the software. # @!method homepage - # @see .homepage= delegate homepage: :"self.class" # The livecheck specification for the software. @@ -461,7 +444,6 @@ def bottle_for_tag(tag = nil) # Whether this formula was loaded using the formulae.brew.sh API # @!method loaded_from_api? - # @private # @see .loaded_from_api? delegate loaded_from_api?: :"self.class" @@ -614,20 +596,17 @@ def aliases # If this {Formula} is installed. # This is actually just a check for if the {#latest_installed_prefix} directory # exists and is not empty. - # @private sig { returns(T::Boolean) } def latest_version_installed? (dir = latest_installed_prefix).directory? && !dir.children.empty? end # If at least one version of {Formula} is installed. - # @private sig { returns(T::Boolean) } def any_version_installed? installed_prefixes.any? { |keg| (keg/Tab::FILENAME).file? } end - # @private # The link status symlink directory for this {Formula}. # You probably want {#opt_prefix} instead. def linked_keg @@ -670,7 +649,6 @@ def head_version_outdated?(version, fetch_head: false) end # The latest prefix for this formula. Checks for {#head} and then {#stable}'s {#prefix} - # @private def latest_installed_prefix if head && (head_version = latest_head_version) && !head_version_outdated?(head_version) latest_head_prefix @@ -724,14 +702,12 @@ def linked_version # The parent of the prefix; the named directory in the cellar containing all # installed versions of this software. - # @private sig { returns(Pathname) } def rack HOMEBREW_CELLAR/name end # All currently installed prefix directories. - # @private def installed_prefixes possible_names.map { |name| HOMEBREW_CELLAR/name } .select(&:directory?) @@ -740,7 +716,6 @@ def installed_prefixes end # All currently installed kegs. - # @private def installed_kegs installed_prefixes.map { |dir| Keg.new(dir) } end @@ -1034,14 +1009,12 @@ def fish_completion # The directory used for as the prefix for {#etc} and {#var} files on # installation so, despite not being in `HOMEBREW_CELLAR`, they are installed # there after pouring a bottle. - # @private sig { returns(Pathname) } def bottle_prefix prefix/".bottle" end # The directory where the formula's installation or test logs will be written. - # @private sig { returns(Pathname) } def logs HOMEBREW_LOGS + name @@ -1202,20 +1175,17 @@ def pour_bottle? true end - # @private delegate pour_bottle_check_unsatisfied_reason: :"self.class" # Can be overridden to run commands on both source and bottle installation. sig { overridable.void } def post_install; end - # @private sig { returns(T::Boolean) } def post_install_defined? method(:post_install).owner != Formula end - # @private sig { void } def install_etc_var etc_var_dirs = [bottle_prefix/"etc", bottle_prefix/"var"] @@ -1226,7 +1196,6 @@ def install_etc_var end end - # @private sig { void } def run_post_install @prefix_returns_versioned_prefix = true @@ -1292,11 +1261,9 @@ def keg_only? keg_only_reason.applicable? end - # @private delegate keg_only_reason: :"self.class" # @see .skip_clean - # @private sig { params(path: Pathname).returns(T::Boolean) } def skip_clean?(path) return true if path.extname == ".la" && self.class.skip_clean_paths.include?(:la) @@ -1306,7 +1273,6 @@ def skip_clean?(path) end # @see .link_overwrite - # @private def link_overwrite?(path) # Don't overwrite files not created by Homebrew. return false if path.stat.uid != HOMEBREW_BREW_FILE.stat.uid @@ -1388,13 +1354,11 @@ def skip_cxxstdlib_check? false end - # @private sig { returns(T::Boolean) } def require_universal_deps? false end - # @private def patch return if patchlist.empty? @@ -1404,7 +1368,6 @@ def patch # Yields |self,staging| with current working directory set to the uncompressed tarball # where staging is a {Mktemp} staging context. - # @private def brew(fetch: true, keep_tmp: false, debug_symbols: false, interactive: false) @prefix_returns_versioned_prefix = true active_spec.fetch if fetch @@ -1439,7 +1402,6 @@ def brew(fetch: true, keep_tmp: false, debug_symbols: false, interactive: false) @prefix_returns_versioned_prefix = false end - # @private def lock @lock = FormulaLock.new(name) @lock.lock @@ -1454,13 +1416,11 @@ def lock end end - # @private def unlock @lock&.unlock @oldname_locks.each(&:unlock) end - # @private sig { returns(T::Array[String]) } def oldnames_to_migrate oldnames.select do |oldname| @@ -1477,7 +1437,6 @@ def migration_needed? !oldnames_to_migrate.empty? && !rack.exist? end - # @private def outdated_kegs(fetch_head: false) raise Migrator::MigrationNeededError.new(oldnames_to_migrate.first, name) if migration_needed? @@ -1560,7 +1519,6 @@ def old_installed_formulae self.class.installed_with_alias_path(alias_path).reject { |f| f.name == name } end - # @private sig { params(fetch_head: T::Boolean).returns(T::Boolean) } def outdated?(fetch_head: false) !outdated_kegs(fetch_head:).empty? @@ -1568,22 +1526,16 @@ def outdated?(fetch_head: false) true end - # @private delegate pinnable?: :@pin - # @private delegate pinned?: :@pin - # @private delegate pinned_version: :@pin - # @private delegate pin: :@pin - # @private delegate unpin: :@pin - # @private def ==(other) self.class == other.class && name == other.name && @@ -1591,19 +1543,16 @@ def ==(other) end alias eql? == - # @private def hash name.hash end - # @private def <=>(other) return unless other.is_a?(Formula) name <=> other.name end - # @private def possible_names [name, *oldnames, *aliases].compact end @@ -1780,7 +1729,6 @@ def deuniversalize_machos(*targets) targets.each { |t| extract_macho_slice_from(Pathname.new(t), Hardware::CPU.arch) } end - # @private sig { params(file: Pathname, arch: T.nilable(Symbol)).void } def extract_macho_slice_from(file, arch = Hardware::CPU.arch) odebug "Extracting #{arch} slice from #{file}" @@ -1905,38 +1853,32 @@ def generate_completions_from_executable(*commands, end # an array of all core {Formula} names - # @private def self.core_names CoreTap.instance.formula_names end # an array of all tap {Formula} names - # @private def self.tap_names @tap_names ||= Tap.reject(&:core_tap?).flat_map(&:formula_names).sort end # an array of all tap {Formula} files - # @private def self.tap_files @tap_files ||= Tap.reject(&:core_tap?).flat_map(&:formula_files) end # an array of all {Formula} names - # @private def self.names @names ||= (core_names + tap_names.map { |name| name.split("/").last }).uniq.sort end # an array of all {Formula} names, which the tap formulae have the fully-qualified name - # @private def self.full_names @full_names ||= core_names + tap_names end # an array of all {Formula} # this should only be used when users specify `--all` to a command - # @private def self.all(eval_all: false) if !eval_all && !Homebrew::EnvConfig.eval_all? raise ArgumentError, "Formula#all without `--eval-all` or HOMEBREW_EVAL_ALL" @@ -1954,7 +1896,6 @@ def self.all(eval_all: false) end # An array of all racks currently installed. - # @private def self.racks Formula.cache[:racks] ||= if HOMEBREW_CELLAR.directory? HOMEBREW_CELLAR.subdirs.reject do |rack| @@ -1966,14 +1907,12 @@ def self.racks end # An array of all currently installed formula names. - # @private sig { returns(T::Array[String]) } def self.installed_formula_names racks.map { |rack| rack.basename.to_s } end # An array of all installed {Formula} - # @private def self.installed Formula.cache[:installed] ||= racks.flat_map do |rack| Formulary.from_rack(rack) @@ -1989,37 +1928,31 @@ def self.installed_with_alias_path(alias_path) end # an array of all alias files of core {Formula} - # @private def self.core_alias_files CoreTap.instance.alias_files end # an array of all core aliases - # @private def self.core_aliases CoreTap.instance.aliases end # an array of all tap aliases - # @private def self.tap_aliases @tap_aliases ||= Tap.reject(&:core_tap?).flat_map(&:aliases).sort end # an array of all aliases - # @private def self.aliases @aliases ||= (core_aliases + tap_aliases.map { |name| name.split("/").last }).uniq.sort end # an array of all aliases as fully-qualified names - # @private def self.alias_full_names @alias_full_names ||= core_aliases + tap_aliases end # Returns a list of approximately matching formula names, but not the complete match - # @private def self.fuzzy_search(name) @spell_checker ||= DidYouMean::SpellChecker.new(dictionary: Set.new(names + full_names).to_a) @spell_checker.correct(name) @@ -2030,14 +1963,12 @@ def self.[](name) end # True if this formula is provided by Homebrew itself - # @private sig { returns(T::Boolean) } def core_formula? !!tap&.core_tap? end # True if this formula is provided by external Tap - # @private sig { returns(T::Boolean) } def tap? return false unless tap @@ -2047,13 +1978,11 @@ def tap? # True if this formula can be installed on this platform # Redefined in extend/os. - # @private sig { returns(T::Boolean) } def valid_platform? requirements.none?(MacOSRequirement) && requirements.none?(LinuxRequirement) end - # @private def print_tap_action(options = {}) return unless tap? @@ -2061,27 +1990,22 @@ def print_tap_action(options = {}) ohai "#{verb} #{name} from #{tap}" end - # @private def tap_git_head tap&.git_head end - # @private delegate env: :"self.class" - # @private delegate conflicts: :"self.class" # 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 - # @private def recursive_dependencies(&block) cache_key = "Formula#recursive_dependencies" unless block Dependency.expand(self, cache_key:, &block) end # The full set of Requirements for this formula's dependency tree. - # @private def recursive_requirements(&block) cache_key = "Formula#recursive_requirements" unless block Requirement.expand(self, cache_key:, &block) @@ -2089,7 +2013,6 @@ def recursive_requirements(&block) # Returns a Keg for the opt_prefix or installed_prefix if they exist. # If not, return `nil`. - # @private def any_installed_keg Formula.cache[:any_installed_keg] ||= {} Formula.cache[:any_installed_keg][full_name] ||= if (installed_prefix = any_installed_prefix) @@ -2112,7 +2035,6 @@ def any_installed_version end # Returns a list of Dependency objects that are required at runtime. - # @private def runtime_dependencies(read_from_tab: true, undeclared: true) deps = if read_from_tab && undeclared && (tab_deps = any_installed_keg&.runtime_dependencies) @@ -2134,7 +2056,6 @@ def runtime_dependencies(read_from_tab: true, undeclared: true) end # Returns a list of {Formula} objects that are required at runtime. - # @private def runtime_formula_dependencies(read_from_tab: true, undeclared: true) cache_key = "#{full_name}-#{read_from_tab}-#{undeclared}" @@ -2179,13 +2100,11 @@ def missing_dependencies(hide: nil) [] end - # @private sig { returns(T.nilable(String)) } def ruby_source_path path.relative_path_from(T.must(tap).path).to_s if tap && path.exist? end - # @private sig { returns(T.nilable(Checksum)) } def ruby_source_checksum Checksum.new(Digest::SHA256.file(path).hexdigest) if path.exist? @@ -2206,7 +2125,6 @@ def merge_spec_dependables(dependables) end private :merge_spec_dependables - # @private def to_hash hsh = { "name" => name, @@ -2292,7 +2210,6 @@ def to_hash hsh end - # @private def to_internal_api_hash api_hash = { "desc" => desc, @@ -2354,7 +2271,6 @@ def to_internal_api_hash api_hash end - # @private def to_hash_with_variations(hash_method: :to_hash) if loaded_from_api? && hash_method == :to_internal_api_hash raise ArgumentError, "API Hash must be generated from Ruby source files" @@ -2437,7 +2353,6 @@ def bottle_hash(compact_for_api: false) hash end - # @private def urls_hash hash = {} @@ -2463,7 +2378,6 @@ def urls_hash hash end - # @private def serialized_requirements requirements = self.class.spec_syms.to_h do |sym| [sym, send(sym)&.requirements] @@ -2489,13 +2403,11 @@ def serialized_requirements end end - # @private def caveats_with_placeholders caveats&.gsub(HOMEBREW_PREFIX, HOMEBREW_PREFIX_PLACEHOLDER) &.gsub(HOMEBREW_CELLAR, HOMEBREW_CELLAR_PLACEHOLDER) end - # @private def dependencies_hash # Create a hash of spec names (stable/head) to the list of dependencies under each dependencies = self.class.spec_syms.to_h do |sym| @@ -2556,22 +2468,18 @@ def dependencies_hash hash end - # @private def on_system_blocks_exist? self.class.on_system_blocks_exist? || @on_system_blocks_exist end - # @private def fetch(verify_download_integrity: true) active_spec.fetch(verify_download_integrity:) end - # @private def verify_download_integrity(filename) active_spec.verify_download_integrity(filename) end - # @private def run_test(keep_tmp: false) @prefix_returns_versioned_prefix = true @@ -2609,16 +2517,13 @@ def run_test(keep_tmp: false) @testpath = nil end - # @private sig { returns(T::Boolean) } def test_defined? false end - # @private def test; end - # @private def test_fixtures(file) HOMEBREW_LIBRARY_PATH/"test/support/fixtures"/file end @@ -2678,7 +2583,6 @@ def setup_home(home) end # Returns a list of Dependency objects that are declared in the formula. - # @private def declared_runtime_dependencies cache_key = "Formula#declared_runtime_dependencies" unless build.any_args_or_options? Dependency.expand(self, cache_key:) do |_, dependency| @@ -2695,7 +2599,6 @@ def declared_runtime_dependencies # Returns a list of Dependency objects that are not declared in the formula # but the formula links to. - # @private def undeclared_runtime_dependencies keg = any_installed_keg return [] unless keg @@ -2837,7 +2740,6 @@ def system(cmd, *args) end end - # @private def eligible_kegs_for_cleanup(quiet: false) eligible_for_cleanup = [] if latest_version_installed? @@ -2932,7 +2834,6 @@ def prepare_patches end # Returns the prefix for a given formula version number. - # @private def versioned_prefix(version) rack/version end @@ -3052,25 +2953,23 @@ def freeze end # Whether this formula was loaded using the formulae.brew.sh API - # @private attr_predicate :loaded_from_api? # Whether this formula contains OS/arch-specific blocks # (e.g. `on_macos`, `on_arm`, `on_monterey :or_older`, `on_system :linux, macos: :big_sur_or_newer`). - # @private attr_predicate :on_system_blocks_exist? - # The reason for why this software is not linked (by default) to - # {::HOMEBREW_PREFIX}. - # @private + # The reason for why this software is not linked (by default) to {::HOMEBREW_PREFIX}. attr_reader :keg_only_reason - # @!attribute [w] desc # A one-line description of the software. Used by users to get an overview # of the software and Homebrew maintainers. # Shows when running `brew info`. # # 
desc "Example formula"
+ # + # @!attribute [w] desc + # @api public attr_rw :desc # @!attribute [w] license @@ -3096,6 +2995,8 @@ def freeze # all_of: ["0BSD", "Zlib", "Artistic-1.0+"], # "Apache-2.0" => { with: "LLVM-exception" }, # ] + # + # @api public def license(args = nil) if args.nil? @licenses @@ -3104,13 +3005,15 @@ def license(args = nil) end 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"
+ # + # @!attribute [w] homepage + # @api public attr_rw :homepage # Whether a livecheck specification is defined or not. @@ -3129,18 +3032,10 @@ def service? @service_block.present? end - # @private - attr_reader :conflicts - - # @private - attr_reader :skip_clean_paths - - # @private - attr_reader :link_overwrite_paths + attr_reader :conflicts, :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. - # @private attr_accessor :pour_bottle_check_unsatisfied_reason # @!attribute [w] revision @@ -3165,13 +3060,11 @@ def service? # 
version_scheme 1
attr_rw :version_scheme - # @private def spec_syms [:stable, :head].freeze end # A list of the {.stable} and {.head} {SoftwareSpec}s. - # @private def specs spec_syms.map do |sym| send(sym) @@ -3258,13 +3151,11 @@ def bottle(&block) stable.bottle(&block) end - # @private def build stable.build end # Get the `BUILD_FLAGS` from the formula's namespace set in `Formulary::load_formula`. - # @private def build_flags namespace = T.must(to_s.split("::")[0..-2]).join("::") return [] if namespace.empty? @@ -3642,9 +3533,6 @@ def pour_bottle?(only_if: nil, &block) @pour_bottle_check.instance_eval(&block) end - # @private - attr_reader :pour_bottle_only_if - # 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. diff --git a/Library/Homebrew/formula_assertions.rb b/Library/Homebrew/formula_assertions.rb index 8f84f6479bd87f..ad9c7ebcc7bd08 100644 --- a/Library/Homebrew/formula_assertions.rb +++ b/Library/Homebrew/formula_assertions.rb @@ -3,8 +3,6 @@ module Homebrew # Helper functions available in formula `test` blocks. - # - # @api private module Assertions include Context diff --git a/Library/Homebrew/formula_auditor.rb b/Library/Homebrew/formula_auditor.rb index 7ac8a334a0cdf1..80ce2f263ba3fd 100644 --- a/Library/Homebrew/formula_auditor.rb +++ b/Library/Homebrew/formula_auditor.rb @@ -9,8 +9,6 @@ module Homebrew # Auditor for checking common violations in {Formula}e. - # - # @api private class FormulaAuditor include FormulaCellarChecks include Utils::Curl diff --git a/Library/Homebrew/formula_cellar_checks.rb b/Library/Homebrew/formula_cellar_checks.rb index afcffb83c9460e..db833443ff57ef 100644 --- a/Library/Homebrew/formula_cellar_checks.rb +++ b/Library/Homebrew/formula_cellar_checks.rb @@ -4,8 +4,6 @@ require "utils/shell" # Checks to perform on a formula's cellar. -# -# @api private module FormulaCellarChecks extend T::Helpers diff --git a/Library/Homebrew/formula_creator.rb b/Library/Homebrew/formula_creator.rb index 32d80792ae6dab..da833cf4eb2ad7 100644 --- a/Library/Homebrew/formula_creator.rb +++ b/Library/Homebrew/formula_creator.rb @@ -6,8 +6,6 @@ module Homebrew # Class for generating a formula from a template. - # - # @api private class FormulaCreator attr_accessor :name diff --git a/Library/Homebrew/formula_free_port.rb b/Library/Homebrew/formula_free_port.rb index 8659c74c5c0a68..d47b8a40a00bb9 100644 --- a/Library/Homebrew/formula_free_port.rb +++ b/Library/Homebrew/formula_free_port.rb @@ -5,8 +5,6 @@ module Homebrew # Helper function for finding a free port. - # - # @api private module FreePort # Returns a free port. # @api public diff --git a/Library/Homebrew/formula_info.rb b/Library/Homebrew/formula_info.rb index 0856c3d49091f3..ea61e7b601e514 100644 --- a/Library/Homebrew/formula_info.rb +++ b/Library/Homebrew/formula_info.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true # Formula information drawn from an external `brew info --json` call. -# -# @api private class FormulaInfo # The whole info structure parsed from the JSON. attr_accessor :info diff --git a/Library/Homebrew/formula_installer.rb b/Library/Homebrew/formula_installer.rb index 4c1503033ba19c..f57931964e1ad1 100644 --- a/Library/Homebrew/formula_installer.rb +++ b/Library/Homebrew/formula_installer.rb @@ -25,8 +25,6 @@ require "attestation" # Installer for a formula. -# -# @api private class FormulaInstaller include FormulaCellarChecks extend Attrable diff --git a/Library/Homebrew/formula_pin.rb b/Library/Homebrew/formula_pin.rb index 829e63d70211f7..0889866b70b8f3 100644 --- a/Library/Homebrew/formula_pin.rb +++ b/Library/Homebrew/formula_pin.rb @@ -4,8 +4,6 @@ require "keg" # Helper functions for pinning a formula. -# -# @api private class FormulaPin def initialize(formula) @formula = formula diff --git a/Library/Homebrew/formula_text_auditor.rb b/Library/Homebrew/formula_text_auditor.rb index 495fa870159cab..273c686b2077a5 100644 --- a/Library/Homebrew/formula_text_auditor.rb +++ b/Library/Homebrew/formula_text_auditor.rb @@ -3,8 +3,6 @@ module Homebrew # Auditor for checking common violations in {Formula} text content. - # - # @api private class FormulaTextAuditor def initialize(path) @text = path.open("rb", &:read) diff --git a/Library/Homebrew/formula_versions.rb b/Library/Homebrew/formula_versions.rb index 89362b88fe13cc..86f763c589cf35 100644 --- a/Library/Homebrew/formula_versions.rb +++ b/Library/Homebrew/formula_versions.rb @@ -4,8 +4,6 @@ require "formula" # Helper class for traversing a formula's previous versions. -# -# @api private class FormulaVersions include Context diff --git a/Library/Homebrew/formulary.rb b/Library/Homebrew/formulary.rb index b8777abd55728c..340a512ee57d97 100644 --- a/Library/Homebrew/formulary.rb +++ b/Library/Homebrew/formulary.rb @@ -13,16 +13,16 @@ # The {Formulary} is responsible for creating instances of {Formula}. # It is not meant to be used directly from formulae. -# -# @api private module Formulary extend Context extend Cachable URL_START_REGEX = %r{(https?|ftp|file)://} + private_constant :URL_START_REGEX - # :codesign and custom requirement classes are not supported + # `:codesign` and custom requirement classes are not supported. API_SUPPORTED_REQUIREMENTS = [:arch, :linux, :macos, :maximum_macos, :xcode].freeze + private_constant :API_SUPPORTED_REQUIREMENTS sig { void } def self.enable_factory_cache! @@ -73,7 +73,6 @@ def self.clear_cache super end - # @private module PathnameWriteMkpath refine Pathname do def write(content, offset = nil, **open_args) diff --git a/Library/Homebrew/git_repository.rb b/Library/Homebrew/git_repository.rb index 5bff80e06dbe4b..bd94e9e16f3896 100644 --- a/Library/Homebrew/git_repository.rb +++ b/Library/Homebrew/git_repository.rb @@ -6,7 +6,6 @@ # Given a {Pathname}, provides methods for querying Git repository information. # @see Utils::Git -# @api private class GitRepository sig { returns(Pathname) } attr_reader :pathname diff --git a/Library/Homebrew/github_packages.rb b/Library/Homebrew/github_packages.rb index 9b1766ea600c3c..68f2f244adee59 100644 --- a/Library/Homebrew/github_packages.rb +++ b/Library/Homebrew/github_packages.rb @@ -8,8 +8,6 @@ require "system_command" # GitHub Packages client. -# -# @api private class GitHubPackages include Context include SystemCommand::Mixin diff --git a/Library/Homebrew/github_releases.rb b/Library/Homebrew/github_releases.rb index 599ae363b90485..4b889516e22c75 100644 --- a/Library/Homebrew/github_releases.rb +++ b/Library/Homebrew/github_releases.rb @@ -5,8 +5,6 @@ require "json" # GitHub Releases client. -# -# @api private class GitHubReleases include Context diff --git a/Library/Homebrew/help.rb b/Library/Homebrew/help.rb index d0c25a21a26426..993ab55eeba6f0 100644 --- a/Library/Homebrew/help.rb +++ b/Library/Homebrew/help.rb @@ -6,8 +6,6 @@ module Homebrew # Helper module for printing help output. - # - # @api private module Help # NOTE: Keep the length of vanilla `--help` less than 25 lines! # This is because the default Terminal height is 25 lines. Scrolling sucks diff --git a/Library/Homebrew/ignorable.rb b/Library/Homebrew/ignorable.rb index 43a7d0af34b0c6..2b5c318f1ea285 100644 --- a/Library/Homebrew/ignorable.rb +++ b/Library/Homebrew/ignorable.rb @@ -7,8 +7,6 @@ end # Provides the ability to optionally ignore errors raised and continue execution. -# -# @api private module Ignorable # Marks exceptions which can be ignored and provides # the ability to jump back to where it was raised. diff --git a/Library/Homebrew/install.rb b/Library/Homebrew/install.rb index 82b0465d9a3381..1f194c10c1392c 100644 --- a/Library/Homebrew/install.rb +++ b/Library/Homebrew/install.rb @@ -9,8 +9,6 @@ module Homebrew # Helper module for performing (pre-)install checks. - # - # @api private module Install class << self def perform_preinstall_checks(all_fatal: false, cc: nil) diff --git a/Library/Homebrew/install_renamed.rb b/Library/Homebrew/install_renamed.rb index 6018da8102a0c1..b16d82893b71ad 100644 --- a/Library/Homebrew/install_renamed.rb +++ b/Library/Homebrew/install_renamed.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true # Helper module for installing default files. -# -# @api private module InstallRenamed def install_p(_, new_basename) super do |src, dst| diff --git a/Library/Homebrew/installed_dependents.rb b/Library/Homebrew/installed_dependents.rb index 5771d7430654cc..0633af88695d9f 100644 --- a/Library/Homebrew/installed_dependents.rb +++ b/Library/Homebrew/installed_dependents.rb @@ -4,8 +4,6 @@ require "cask_dependent" # Helper functions for installed dependents. -# -# @api private module InstalledDependents module_function diff --git a/Library/Homebrew/keg.rb b/Library/Homebrew/keg.rb index 5c77bb8a96bf50..0974e3206812b5 100644 --- a/Library/Homebrew/keg.rb +++ b/Library/Homebrew/keg.rb @@ -7,8 +7,6 @@ require "extend/cachable" # Installation prefix of a formula. -# -# @api private class Keg extend Cachable diff --git a/Library/Homebrew/language/python.rb b/Library/Homebrew/language/python.rb index e341d358b063c3..71ef9e9bc340e3 100644 --- a/Library/Homebrew/language/python.rb +++ b/Library/Homebrew/language/python.rb @@ -202,8 +202,6 @@ def virtualenv_create(venv_root, python = "python", formula = T.cast(self, Formu # "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. - # - # @api private sig { params(python: String).returns(T::Boolean) } def needs_python?(python) return true if build.with?(python) diff --git a/Library/Homebrew/lazy_object.rb b/Library/Homebrew/lazy_object.rb index f43d316e1efe70..7f702977ee55c2 100644 --- a/Library/Homebrew/lazy_object.rb +++ b/Library/Homebrew/lazy_object.rb @@ -4,8 +4,6 @@ require "delegate" # An object which lazily evaluates its inner block only once a method is called on it. -# -# @api private class LazyObject < Delegator def initialize(&callable) super(callable) diff --git a/Library/Homebrew/linkage_checker.rb b/Library/Homebrew/linkage_checker.rb index 6a0bfa39622da2..dec594f9876f03 100644 --- a/Library/Homebrew/linkage_checker.rb +++ b/Library/Homebrew/linkage_checker.rb @@ -7,8 +7,6 @@ require "fiddle" # Check for broken/missing linkage in a formula's keg. -# -# @api private class LinkageChecker attr_reader :undeclared_deps, :keg, :formula, :store diff --git a/Library/Homebrew/livecheck/error.rb b/Library/Homebrew/livecheck/error.rb index 8cbd8ff28e2951..1c0be81b4cbe7c 100644 --- a/Library/Homebrew/livecheck/error.rb +++ b/Library/Homebrew/livecheck/error.rb @@ -4,8 +4,6 @@ module Homebrew module Livecheck # Error during a livecheck run. - # - # @api private class Error < RuntimeError end end diff --git a/Library/Homebrew/livecheck/livecheck.rb b/Library/Homebrew/livecheck/livecheck.rb index 190c92e4475cb2..98811338a9edcc 100644 --- a/Library/Homebrew/livecheck/livecheck.rb +++ b/Library/Homebrew/livecheck/livecheck.rb @@ -13,8 +13,6 @@ module Homebrew # The {Livecheck} module consists of methods used by the `brew livecheck` # command. These methods print the requested livecheck information # for formulae. - # - # @api private module Livecheck module_function diff --git a/Library/Homebrew/livecheck/livecheck_version.rb b/Library/Homebrew/livecheck/livecheck_version.rb index bee235413dbbdf..8c06b80722e2dc 100644 --- a/Library/Homebrew/livecheck/livecheck_version.rb +++ b/Library/Homebrew/livecheck/livecheck_version.rb @@ -4,8 +4,6 @@ module Homebrew module Livecheck # A formula or cask version, split into its component sub-versions. - # - # @api private class LivecheckVersion include Comparable diff --git a/Library/Homebrew/livecheck/skip_conditions.rb b/Library/Homebrew/livecheck/skip_conditions.rb index dc19de5916c1a2..e868d7640d1f1f 100644 --- a/Library/Homebrew/livecheck/skip_conditions.rb +++ b/Library/Homebrew/livecheck/skip_conditions.rb @@ -5,8 +5,6 @@ module Homebrew module Livecheck # The `Livecheck::SkipConditions` module primarily contains methods that # check for various formula/cask/resource conditions where a check should be skipped. - # - # @api private module SkipConditions module_function diff --git a/Library/Homebrew/livecheck/strategy.rb b/Library/Homebrew/livecheck/strategy.rb index 68f0d34bd1e738..e3f8d8d61d412d 100644 --- a/Library/Homebrew/livecheck/strategy.rb +++ b/Library/Homebrew/livecheck/strategy.rb @@ -7,8 +7,6 @@ module Livecheck # as some general-purpose methods for working with them. Within the context # of the `brew livecheck` command, strategies are established procedures # for finding new software versions at a given source. - # - # @api private module Strategy extend Utils::Curl diff --git a/Library/Homebrew/livecheck/strategy/electron_builder.rb b/Library/Homebrew/livecheck/strategy/electron_builder.rb index 7ec7dcb03f27e1..e2a413ba52c065 100644 --- a/Library/Homebrew/livecheck/strategy/electron_builder.rb +++ b/Library/Homebrew/livecheck/strategy/electron_builder.rb @@ -9,8 +9,6 @@ module Strategy # # This strategy is not applied automatically and it's necessary to use # `strategy :electron_builder` in a `livecheck` block to apply it. - # - # @api private class ElectronBuilder NICE_NAME = "electron-builder" diff --git a/Library/Homebrew/livecheck/strategy/extract_plist.rb b/Library/Homebrew/livecheck/strategy/extract_plist.rb index 8f2e50e882678a..c59d848abda96c 100644 --- a/Library/Homebrew/livecheck/strategy/extract_plist.rb +++ b/Library/Homebrew/livecheck/strategy/extract_plist.rb @@ -16,8 +16,6 @@ module Strategy # # This strategy is not applied automatically and it's necessary to use # `strategy :extract_plist` in a `livecheck` block to apply it. - # - # @api private class ExtractPlist # A priority of zero causes livecheck to skip the strategy. We do this # for {ExtractPlist} so we can selectively apply it when appropriate. @@ -35,9 +33,7 @@ def self.match?(url) URL_MATCH_REGEX.match?(url) end - # @api private Item = Struct.new( - # @api private :bundle_version, keyword_init: true, ) do diff --git a/Library/Homebrew/livecheck/strategy/header_match.rb b/Library/Homebrew/livecheck/strategy/header_match.rb index ae2a7c76ce8103..152cf046db223a 100644 --- a/Library/Homebrew/livecheck/strategy/header_match.rb +++ b/Library/Homebrew/livecheck/strategy/header_match.rb @@ -9,8 +9,6 @@ module Strategy # # This strategy is not applied automatically and it's necessary to use # `strategy :header_match` in a `livecheck` block to apply it. - # - # @api private class HeaderMatch NICE_NAME = "Header match" diff --git a/Library/Homebrew/livecheck/strategy/sparkle.rb b/Library/Homebrew/livecheck/strategy/sparkle.rb index 5b9f9e1df8dcf4..c875ec44147fd6 100644 --- a/Library/Homebrew/livecheck/strategy/sparkle.rb +++ b/Library/Homebrew/livecheck/strategy/sparkle.rb @@ -11,8 +11,6 @@ module Strategy # # This strategy is not applied automatically and it's necessary to use # `strategy :sparkle` in a `livecheck` block to apply it. - # - # @api private class Sparkle # A priority of zero causes livecheck to skip the strategy. We do this # for {Sparkle} so we can selectively apply it when appropriate. @@ -33,7 +31,6 @@ def self.match?(url) URL_MATCH_REGEX.match?(url) end - # @api private Item = Struct.new( # @api public :title, diff --git a/Library/Homebrew/locale.rb b/Library/Homebrew/locale.rb index b07b830585fbe2..b6cda9a6e78155 100644 --- a/Library/Homebrew/locale.rb +++ b/Library/Homebrew/locale.rb @@ -4,8 +4,6 @@ # Representation of a system locale. # # Used to compare the system language and languages defined using the cask `language` stanza. -# -# @api private class Locale # Error when a string cannot be parsed to a `Locale`. class ParserError < StandardError diff --git a/Library/Homebrew/lock_file.rb b/Library/Homebrew/lock_file.rb index ca17b61279e325..73adbb0c51837f 100644 --- a/Library/Homebrew/lock_file.rb +++ b/Library/Homebrew/lock_file.rb @@ -4,8 +4,6 @@ require "fcntl" # A lock file. -# -# @api private class LockFile attr_reader :path @@ -52,8 +50,6 @@ def create_lockfile end # A lock file for a formula. -# -# @api private class FormulaLock < LockFile def initialize(name) super("#{name}.formula") @@ -61,8 +57,6 @@ def initialize(name) end # A lock file for a cask. -# -# @api private class CaskLock < LockFile def initialize(name) super("#{name}.cask") diff --git a/Library/Homebrew/macos_version.rb b/Library/Homebrew/macos_version.rb index a4ff1e3029a5aa..c03c7d46b7223b 100644 --- a/Library/Homebrew/macos_version.rb +++ b/Library/Homebrew/macos_version.rb @@ -4,8 +4,6 @@ require "version" # A macOS version. -# -# @api private class MacOSVersion < Version # Raised when a macOS version is unsupported. class Error < RuntimeError diff --git a/Library/Homebrew/manpages.rb b/Library/Homebrew/manpages.rb index 316022f4de900c..ead19024c3e863 100644 --- a/Library/Homebrew/manpages.rb +++ b/Library/Homebrew/manpages.rb @@ -9,8 +9,6 @@ TARGET_DOC_PATH = (HOMEBREW_REPOSITORY/"docs").freeze module Homebrew # Helper functions for generating homebrew manual. - # - # @api private module Manpages Variables = Struct.new( :alumni, diff --git a/Library/Homebrew/metafiles.rb b/Library/Homebrew/metafiles.rb index e7e71963df0887..9f3a74239f4010 100644 --- a/Library/Homebrew/metafiles.rb +++ b/Library/Homebrew/metafiles.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true # Helper for checking if a file is considered a metadata file. -# -# @api private module Metafiles LICENSES = Set.new(%w[copying copyright license licence]).freeze # {https://github.com/github/markup#markups} diff --git a/Library/Homebrew/migrator.rb b/Library/Homebrew/migrator.rb index 0e08423bb4d29f..9c6c0cb06cd9c7 100644 --- a/Library/Homebrew/migrator.rb +++ b/Library/Homebrew/migrator.rb @@ -6,8 +6,6 @@ require "tab" # Helper class for migrating a formula from an old to a new name. -# -# @api private class Migrator include Context diff --git a/Library/Homebrew/missing_formula.rb b/Library/Homebrew/missing_formula.rb index 6bf851b1d858c7..7a49643accd2c3 100644 --- a/Library/Homebrew/missing_formula.rb +++ b/Library/Homebrew/missing_formula.rb @@ -5,8 +5,6 @@ module Homebrew # Helper module for checking if there is a reason a formula is missing. - # - # @api private module MissingFormula class << self def reason(name, silent: false, show_info: false) diff --git a/Library/Homebrew/options.rb b/Library/Homebrew/options.rb index 17ff40168d38fa..53bf8d608fa3da 100644 --- a/Library/Homebrew/options.rb +++ b/Library/Homebrew/options.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true # A formula option. -# -# @api private class Option attr_reader :name, :description, :flag @@ -39,8 +37,6 @@ def inspect end # A deprecated formula option. -# -# @api private class DeprecatedOption attr_reader :old, :current @@ -66,8 +62,6 @@ def ==(other) end # A collection of formula options. -# -# @api private class Options include Enumerable diff --git a/Library/Homebrew/os.rb b/Library/Homebrew/os.rb index 899fbf10b79130..6e82f31fac5cb7 100644 --- a/Library/Homebrew/os.rb +++ b/Library/Homebrew/os.rb @@ -4,8 +4,6 @@ require "version" # Helper functions for querying operating system information. -# -# @api private module OS # Check if the operating system is macOS. # diff --git a/Library/Homebrew/os/linux/elf.rb b/Library/Homebrew/os/linux/elf.rb index efd855db952ca3..7c0c7f48bc354a 100644 --- a/Library/Homebrew/os/linux/elf.rb +++ b/Library/Homebrew/os/linux/elf.rb @@ -3,8 +3,6 @@ # {Pathname} extension for dealing with ELF files. # @see https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header -# -# @api private module ELFShim MAGIC_NUMBER_OFFSET = 0 private_constant :MAGIC_NUMBER_OFFSET @@ -119,8 +117,6 @@ def dynamic_elf? end # Helper class for reading metadata from an ELF file. - # - # @api private class Metadata attr_reader :path, :dylib_id, :dylibs diff --git a/Library/Homebrew/os/linux/glibc.rb b/Library/Homebrew/os/linux/glibc.rb index 440af7521dbed4..caa392f889a8de 100644 --- a/Library/Homebrew/os/linux/glibc.rb +++ b/Library/Homebrew/os/linux/glibc.rb @@ -4,8 +4,6 @@ module OS module Linux # Helper functions for querying `glibc` information. - # - # @api private module Glibc module_function diff --git a/Library/Homebrew/os/linux/kernel.rb b/Library/Homebrew/os/linux/kernel.rb index 0fe09b39526aed..a3d7a614630c78 100644 --- a/Library/Homebrew/os/linux/kernel.rb +++ b/Library/Homebrew/os/linux/kernel.rb @@ -4,8 +4,6 @@ module OS module Linux # Helper functions for querying Linux kernel information. - # - # @api private module Kernel module_function diff --git a/Library/Homebrew/os/mac/mach.rb b/Library/Homebrew/os/mac/mach.rb index 1580f06b9be9e3..b344cf6c79474c 100644 --- a/Library/Homebrew/os/mac/mach.rb +++ b/Library/Homebrew/os/mac/mach.rb @@ -4,8 +4,6 @@ require "macho" # {Pathname} extension for dealing with Mach-O files. -# -# @api private module MachOShim extend Forwardable diff --git a/Library/Homebrew/os/mac/sdk.rb b/Library/Homebrew/os/mac/sdk.rb index 44d5dd7df4b6c7..59471c744dcc86 100644 --- a/Library/Homebrew/os/mac/sdk.rb +++ b/Library/Homebrew/os/mac/sdk.rb @@ -6,8 +6,6 @@ module OS module Mac # Class representing a macOS SDK. - # - # @api private class SDK # 11.x SDKs are explicitly excluded - we want the MacOSX11.sdk symlink instead. VERSIONED_SDK_REGEX = /MacOSX(10\.\d+|\d+)\.sdk$/ @@ -30,8 +28,6 @@ def initialize(version, path, source) end # Base class for SDK locators. - # - # @api private class BaseSDKLocator extend T::Helpers include SystemCommand::Mixin @@ -141,8 +137,6 @@ def read_sdk_version(sdk_path) private_constant :BaseSDKLocator # Helper class for locating the Xcode SDK. - # - # @api private class XcodeSDKLocator < BaseSDKLocator sig { override.returns(Symbol) } def source @@ -166,8 +160,6 @@ def sdk_prefix end # Helper class for locating the macOS Command Line Tools SDK. - # - # @api private class CLTSDKLocator < BaseSDKLocator sig { override.returns(Symbol) } def source diff --git a/Library/Homebrew/os/mac/xcode.rb b/Library/Homebrew/os/mac/xcode.rb index aa159b69f90669..bd5d4c24331e49 100644 --- a/Library/Homebrew/os/mac/xcode.rb +++ b/Library/Homebrew/os/mac/xcode.rb @@ -4,8 +4,6 @@ module OS module Mac # Helper module for querying Xcode information. - # - # @api private module Xcode DEFAULT_BUNDLE_PATH = Pathname("/Applications/Xcode.app").freeze BUNDLE_ID = "com.apple.dt.Xcode" @@ -264,8 +262,6 @@ def self.default_prefix? end # Helper module for querying macOS Command Line Tools information. - # - # @api private module CLT # The original Mavericks CLT package ID EXECUTABLE_PKG_ID = "com.apple.pkg.CLTools_Executables" diff --git a/Library/Homebrew/patch.rb b/Library/Homebrew/patch.rb index 971f6c6dca1bf7..2f7cceae958c53 100644 --- a/Library/Homebrew/patch.rb +++ b/Library/Homebrew/patch.rb @@ -5,8 +5,6 @@ require "erb" # Helper module for creating patches. -# -# @api private module Patch def self.create(strip, src, &block) case strip @@ -32,8 +30,6 @@ def self.create(strip, src, &block) end # An abstract class representing a patch embedded into a formula. -# -# @api private class EmbeddedPatch attr_writer :owner attr_reader :strip @@ -62,8 +58,6 @@ def inspect end # A patch at the `__END__` of a formula file. -# -# @api private class DATAPatch < EmbeddedPatch attr_accessor :path @@ -89,8 +83,6 @@ def contents end # A string containing a patch. -# -# @api private class StringPatch < EmbeddedPatch def initialize(strip, str) super(strip) @@ -103,8 +95,6 @@ def contents end # A string containing a patch. -# -# @api private class ExternalPatch extend Forwardable diff --git a/Library/Homebrew/pkg_version.rb b/Library/Homebrew/pkg_version.rb index e63877aafca977..0cfebe18da9d32 100644 --- a/Library/Homebrew/pkg_version.rb +++ b/Library/Homebrew/pkg_version.rb @@ -4,8 +4,6 @@ require "version" # Combination of a version and a revision. -# -# @api private class PkgVersion include Comparable extend Forwardable diff --git a/Library/Homebrew/readall.rb b/Library/Homebrew/readall.rb index 86ad869d790267..c20251fbb18116 100644 --- a/Library/Homebrew/readall.rb +++ b/Library/Homebrew/readall.rb @@ -6,8 +6,6 @@ require "system_command" # Helper module for validating syntax in taps. -# -# @api private module Readall extend Cachable extend SystemCommand::Mixin diff --git a/Library/Homebrew/requirement.rb b/Library/Homebrew/requirement.rb index 3e0c5ffff3a4c0..d8df3552e9cbbe 100644 --- a/Library/Homebrew/requirement.rb +++ b/Library/Homebrew/requirement.rb @@ -10,8 +10,6 @@ # A base class for non-formula requirements needed by formulae. # A fatal requirement is one that will fail the build if it is not present. # By default, requirements are non-fatal. -# -# @api private class Requirement include Dependable extend Cachable diff --git a/Library/Homebrew/requirements/arch_requirement.rb b/Library/Homebrew/requirements/arch_requirement.rb index 17ce1c27015323..48ed2573d6e920 100644 --- a/Library/Homebrew/requirements/arch_requirement.rb +++ b/Library/Homebrew/requirements/arch_requirement.rb @@ -4,8 +4,6 @@ require "requirement" # A requirement on a specific architecture. -# -# @api private class ArchRequirement < Requirement fatal true diff --git a/Library/Homebrew/requirements/codesign_requirement.rb b/Library/Homebrew/requirements/codesign_requirement.rb index 7a006472c70f9b..74e73905f7d277 100644 --- a/Library/Homebrew/requirements/codesign_requirement.rb +++ b/Library/Homebrew/requirements/codesign_requirement.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true # A requirement on a code-signing identity. -# -# @api private class CodesignRequirement < Requirement fatal true diff --git a/Library/Homebrew/requirements/linux_requirement.rb b/Library/Homebrew/requirements/linux_requirement.rb index 058f5a116682c8..e0aa5def4900aa 100644 --- a/Library/Homebrew/requirements/linux_requirement.rb +++ b/Library/Homebrew/requirements/linux_requirement.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true # A requirement on Linux. -# -# @api private class LinuxRequirement < Requirement fatal true diff --git a/Library/Homebrew/requirements/macos_requirement.rb b/Library/Homebrew/requirements/macos_requirement.rb index b58a3ce50dc871..0e7e0cd06e2ccd 100644 --- a/Library/Homebrew/requirements/macos_requirement.rb +++ b/Library/Homebrew/requirements/macos_requirement.rb @@ -4,8 +4,6 @@ require "requirement" # A requirement on macOS. -# -# @api private class MacOSRequirement < Requirement fatal true diff --git a/Library/Homebrew/requirements/xcode_requirement.rb b/Library/Homebrew/requirements/xcode_requirement.rb index 097d0d3e07f7ca..0494fd5fae110a 100644 --- a/Library/Homebrew/requirements/xcode_requirement.rb +++ b/Library/Homebrew/requirements/xcode_requirement.rb @@ -4,8 +4,6 @@ require "requirement" # A requirement on Xcode. -# -# @api private class XcodeRequirement < Requirement fatal true diff --git a/Library/Homebrew/resource.rb b/Library/Homebrew/resource.rb index fc00c8dccc824a..f8fa9f956f40be 100644 --- a/Library/Homebrew/resource.rb +++ b/Library/Homebrew/resource.rb @@ -9,8 +9,6 @@ # Resource is the fundamental representation of an external resource. The # primary formula download, along with other declared resources, are instances # of this class. -# -# @api private class Resource < Downloadable include FileUtils include OnSystem::MacOSAndLinux @@ -287,8 +285,6 @@ def directory(val = nil) # The context in which a {Resource#stage} occurs. Supports access to both # the {Resource} and associated {Mktemp} in a single block argument. The interface # is back-compatible with {Resource} itself as used in that context. -# -# @api private class ResourceStageContext extend Forwardable diff --git a/Library/Homebrew/resource_auditor.rb b/Library/Homebrew/resource_auditor.rb index eb29bf3b546ecb..796af321e55a26 100644 --- a/Library/Homebrew/resource_auditor.rb +++ b/Library/Homebrew/resource_auditor.rb @@ -3,8 +3,6 @@ module Homebrew # Auditor for checking common violations in {Resource}s. - # - # @api private class ResourceAuditor include Utils::Curl diff --git a/Library/Homebrew/rubocops/bottle.rb b/Library/Homebrew/rubocops/bottle.rb index 556d3c78421b2c..ddbbff8331bbb6 100644 --- a/Library/Homebrew/rubocops/bottle.rb +++ b/Library/Homebrew/rubocops/bottle.rb @@ -7,8 +7,6 @@ module RuboCop module Cop module FormulaAudit # This cop audits the `bottle` block in formulae. - # - # @api private class BottleFormat < FormulaCop extend AutoCorrector @@ -54,8 +52,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop audits the indentation of the bottle tags in the `bottle` block in formulae. - # - # @api private class BottleTagIndentation < FormulaCop extend AutoCorrector @@ -90,8 +86,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop audits the indentation of the sha256 digests in the`bottle` block in formulae. - # - # @api private class BottleDigestIndentation < FormulaCop extend AutoCorrector @@ -126,8 +120,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop audits the order of the `bottle` block in formulae. - # - # @api private class BottleOrder < FormulaCop extend AutoCorrector diff --git a/Library/Homebrew/rubocops/caveats.rb b/Library/Homebrew/rubocops/caveats.rb index 417de01d5f0a75..048ddd5bf9101a 100644 --- a/Library/Homebrew/rubocops/caveats.rb +++ b/Library/Homebrew/rubocops/caveats.rb @@ -22,8 +22,6 @@ module FormulaAudit # Use `sudo` to run the executable. # EOS # end - # - # @api private class Caveats < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, _body_node) caveats_strings.each do |n| diff --git a/Library/Homebrew/rubocops/checksum.rb b/Library/Homebrew/rubocops/checksum.rb index 52e01584db4280..d2bf8310b1aebf 100644 --- a/Library/Homebrew/rubocops/checksum.rb +++ b/Library/Homebrew/rubocops/checksum.rb @@ -7,8 +7,6 @@ module RuboCop module Cop module FormulaAudit # This cop makes sure that deprecated checksums are not used. - # - # @api private class Checksum < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? @@ -43,8 +41,6 @@ def audit_sha256(checksum) end # This cop makes sure that checksum strings are lowercase. - # - # @api private class ChecksumCase < FormulaCop extend AutoCorrector diff --git a/Library/Homebrew/rubocops/class.rb b/Library/Homebrew/rubocops/class.rb index 1d1a1b0c5bf07e..d23617e990457f 100644 --- a/Library/Homebrew/rubocops/class.rb +++ b/Library/Homebrew/rubocops/class.rb @@ -7,8 +7,6 @@ module RuboCop module Cop module FormulaAudit # This cop makes sure that {Formula} is used as superclass. - # - # @api private class ClassName < FormulaCop extend AutoCorrector @@ -29,8 +27,6 @@ def audit_formula(_node, _class_node, parent_class_node, _body_node) end # This cop makes sure that a `test` block contains a proper test. - # - # @api private class Test < FormulaCop extend AutoCorrector @@ -72,8 +68,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) module FormulaAuditStrict # This cop makes sure that a `test` block exists. - # - # @api private class TestPresent < FormulaCop def audit_formula(_node, class_node, _parent_class_node, body_node) return if find_block(body_node, :test) diff --git a/Library/Homebrew/rubocops/components_redundancy.rb b/Library/Homebrew/rubocops/components_redundancy.rb index e6d80186912947..463bf3da5da8ce 100644 --- a/Library/Homebrew/rubocops/components_redundancy.rb +++ b/Library/Homebrew/rubocops/components_redundancy.rb @@ -14,8 +14,6 @@ module FormulaAudit # - `stable do` should not be present without a `head` spec # - `stable do` should not be present with only `url|checksum|mirror|version` # - `head do` should not be present with only `url` - # - # @api private class ComponentsRedundancy < FormulaCop HEAD_MSG = "`head` and `head do` should not be simultaneously present" BOTTLE_MSG = "`bottle :modifier` and `bottle do` should not be simultaneously present" diff --git a/Library/Homebrew/rubocops/extend/formula_cop.rb b/Library/Homebrew/rubocops/extend/formula_cop.rb index 6cfaa7b9f601fc..02f1ad1ec10a47 100644 --- a/Library/Homebrew/rubocops/extend/formula_cop.rb +++ b/Library/Homebrew/rubocops/extend/formula_cop.rb @@ -6,8 +6,6 @@ module RuboCop module Cop # Abstract base class for all formula cops. - # - # @api private class FormulaCop < Base extend T::Helpers include RangeHelp diff --git a/Library/Homebrew/rubocops/files.rb b/Library/Homebrew/rubocops/files.rb index 33443232deb52e..abce494eb7e047 100644 --- a/Library/Homebrew/rubocops/files.rb +++ b/Library/Homebrew/rubocops/files.rb @@ -7,8 +7,6 @@ module RuboCop module Cop module FormulaAudit # This cop makes sure that a formula's file permissions are correct. - # - # @api private class Files < FormulaCop def audit_formula(node, _class_node, _parent_class_node, _body_node) return unless file_path diff --git a/Library/Homebrew/rubocops/io_read.rb b/Library/Homebrew/rubocops/io_read.rb index 3db249031e4699..0b58afea018677 100644 --- a/Library/Homebrew/rubocops/io_read.rb +++ b/Library/Homebrew/rubocops/io_read.rb @@ -5,8 +5,6 @@ module RuboCop module Cop module Homebrew # This cop restricts usage of IO.read functions for security reasons. - # - # @api private class IORead < Base MSG = "The use of `IO.%s` is a security risk." RESTRICT_ON_SEND = [:read, :readlines].freeze diff --git a/Library/Homebrew/rubocops/keg_only.rb b/Library/Homebrew/rubocops/keg_only.rb index 80540399efcfdf..40722479623c08 100644 --- a/Library/Homebrew/rubocops/keg_only.rb +++ b/Library/Homebrew/rubocops/keg_only.rb @@ -7,8 +7,6 @@ module RuboCop module Cop module FormulaAudit # This cop makes sure that a `keg_only` reason has the correct format. - # - # @api private class KegOnly < FormulaCop extend AutoCorrector diff --git a/Library/Homebrew/rubocops/lines.rb b/Library/Homebrew/rubocops/lines.rb index f1bf210b41e704..6d51e275d5d8a4 100644 --- a/Library/Homebrew/rubocops/lines.rb +++ b/Library/Homebrew/rubocops/lines.rb @@ -9,8 +9,6 @@ module RuboCop module Cop module FormulaAudit # This cop checks for various miscellaneous Homebrew coding styles. - # - # @api private class Lines < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, _body_node) [:automake, :ant, :autoconf, :emacs, :expat, :libtool, :mysql, :perl, @@ -32,8 +30,6 @@ def audit_formula(_node, _class_node, _parent_class_node, _body_node) end # This cop makes sure that a space is used for class inheritance. - # - # @api private class ClassInheritance < FormulaCop def audit_formula(_node, class_node, parent_class_node, _body_node) begin_pos = start_column(parent_class_node) @@ -46,8 +42,6 @@ def audit_formula(_node, class_node, parent_class_node, _body_node) end # This cop makes sure that template comments are removed. - # - # @api private class Comments < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, _body_node) audit_comments do |comment| @@ -87,8 +81,6 @@ def audit_formula(_node, _class_node, _parent_class_node, _body_node) end # This cop makes sure that idiomatic `assert_*` statements are used. - # - # @api private class AssertStatements < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? @@ -114,8 +106,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure that `option`s are used idiomatically. - # - # @api private class OptionDeclarations < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? @@ -199,8 +189,6 @@ def unless_modifier?(node) end # This cop makes sure that formulae depend on `open-mpi` instead of `mpich`. - # - # @api private class MpiCheck < FormulaCop extend AutoCorrector @@ -220,8 +208,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure that formulae depend on `openssl` instead of `quictls`. - # - # @api private class QuicTLSCheck < FormulaCop extend AutoCorrector @@ -242,8 +228,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) # This cop makes sure that formulae do not depend on `pyoxidizer` at build-time # or run-time. - # - # @api private class PyoxidizerCheck < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? @@ -256,8 +240,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure that the safe versions of `popen_*` calls are used. - # - # @api private class SafePopenCommands < FormulaCop extend AutoCorrector @@ -287,8 +269,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure that environment variables are passed correctly to `popen_*` calls. - # - # @api private class ShellVariables < FormulaCop extend AutoCorrector @@ -319,8 +299,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure that `license` has the correct format. - # - # @api private class LicenseArrays < FormulaCop extend AutoCorrector @@ -340,8 +318,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure that nested `license` declarations are split onto multiple lines. - # - # @api private class Licenses < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? @@ -363,8 +339,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure that Python versions are consistent. - # - # @api private class PythonVersions < FormulaCop extend AutoCorrector @@ -409,8 +383,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure that OS conditionals are consistent. - # - # @api private class OnSystemConditionals < FormulaCop include OnSystemConditionalsHelper extend AutoCorrector @@ -450,8 +422,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure the `MacOS` module is not used in Linux-facing formula code - # - # @api private class MacOSOnLinux < FormulaCop include OnSystemConditionalsHelper @@ -465,8 +435,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure that the `generate_completions_from_executable` DSL is used. - # - # @api private class GenerateCompletionsDSL < FormulaCop extend AutoCorrector @@ -548,8 +516,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) # This cop makes sure that the `generate_completions_from_executable` DSL is used with only # a single, combined call for all shells. - # - # @api private class SingleGenerateCompletionsDSLCall < FormulaCop extend AutoCorrector @@ -610,8 +576,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop checks for other miscellaneous style violations. - # - # @api private class Miscellaneous < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? @@ -881,8 +845,6 @@ def modifier?(node) module FormulaAuditStrict # This cop makes sure that no build-time checks are performed. - # - # @api private class MakeCheck < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if formula_tap != "homebrew-core" @@ -917,8 +879,6 @@ def audit_formula(_node, _class_node, _parent_class_node, _body_node) end # This cop makes sure that formulae build with `rust` instead of `rustup-init`. - # - # @api private class RustCheck < FormulaCop extend AutoCorrector diff --git a/Library/Homebrew/rubocops/livecheck.rb b/Library/Homebrew/rubocops/livecheck.rb index 084f43c3eefd99..7a974fdcf8fa7d 100644 --- a/Library/Homebrew/rubocops/livecheck.rb +++ b/Library/Homebrew/rubocops/livecheck.rb @@ -8,8 +8,6 @@ module Cop module FormulaAudit # This cop ensures that no other livecheck information is provided for # skipped formulae. - # - # @api private class LivecheckSkip < FormulaCop extend AutoCorrector @@ -40,8 +38,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop ensures that a `url` is specified in the `livecheck` block. - # - # @api private class LivecheckUrlProvided < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) livecheck_node = find_block(body_node, :livecheck) @@ -63,8 +59,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) # This cop ensures that a supported symbol (`head`, `stable, `homepage`) # is used when the livecheck `url` is identical to one of these formula URLs. - # - # @api private class LivecheckUrlSymbol < FormulaCop extend AutoCorrector @@ -120,8 +114,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop ensures that the `regex` call in the `livecheck` block uses parentheses. - # - # @api private class LivecheckRegexParentheses < FormulaCop extend AutoCorrector @@ -147,8 +139,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) # This cop ensures that the pattern provided to livecheck's `regex` uses `\.t` instead of # `\.tgz`, `\.tar.gz` and variants. - # - # @api private class LivecheckRegexExtension < FormulaCop extend AutoCorrector @@ -180,8 +170,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) # This cop ensures that a `regex` is provided when `strategy :page_match` is specified # in the `livecheck` block. - # - # @api private class LivecheckRegexIfPageMatch < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) livecheck_node = find_block(body_node, :livecheck) @@ -206,8 +194,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) # This cop ensures that the `regex` provided to livecheck is case-insensitive, # unless sensitivity is explicitly required for proper matching. - # - # @api private class LivecheckRegexCaseInsensitive < FormulaCop extend AutoCorrector diff --git a/Library/Homebrew/rubocops/move_to_extend_os.rb b/Library/Homebrew/rubocops/move_to_extend_os.rb index f5a1f9bfe3b062..a0177589460401 100644 --- a/Library/Homebrew/rubocops/move_to_extend_os.rb +++ b/Library/Homebrew/rubocops/move_to_extend_os.rb @@ -5,8 +5,6 @@ module RuboCop module Cop module Homebrew # This cop ensures that platform specific code ends up in `extend/os`. - # - # @api private class MoveToExtendOS < Base MSG = "Move `OS.linux?` and `OS.mac?` calls to `extend/os`." diff --git a/Library/Homebrew/rubocops/resource_requires_dependencies.rb b/Library/Homebrew/rubocops/resource_requires_dependencies.rb index 1ddcf561118823..ec2d15a1044984 100644 --- a/Library/Homebrew/rubocops/resource_requires_dependencies.rb +++ b/Library/Homebrew/rubocops/resource_requires_dependencies.rb @@ -9,8 +9,6 @@ module FormulaAudit # This cop audits Python formulae that include certain resources # to ensure that they also have the correct `uses_from_macos` # dependencies. - # - # @api private class ResourceRequiresDependencies < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? diff --git a/Library/Homebrew/rubocops/service.rb b/Library/Homebrew/rubocops/service.rb index d711df7d6a0bbb..a141e6fc749318 100644 --- a/Library/Homebrew/rubocops/service.rb +++ b/Library/Homebrew/rubocops/service.rb @@ -7,8 +7,6 @@ module RuboCop module Cop module FormulaAudit # This cop audits the service block. - # - # @api private class Service < FormulaCop extend AutoCorrector diff --git a/Library/Homebrew/rubocops/shared/desc_helper.rb b/Library/Homebrew/rubocops/shared/desc_helper.rb index 85a7c6dd43c7ce..550bad0112a9b3 100644 --- a/Library/Homebrew/rubocops/shared/desc_helper.rb +++ b/Library/Homebrew/rubocops/shared/desc_helper.rb @@ -6,8 +6,6 @@ module RuboCop module Cop # This module performs common checks the `desc` field in both formulae and casks. - # - # @api private module DescHelper include HelperFunctions diff --git a/Library/Homebrew/rubocops/shared/helper_functions.rb b/Library/Homebrew/rubocops/shared/helper_functions.rb index 2d728b8a11cc1f..4a62e02b2f07e7 100644 --- a/Library/Homebrew/rubocops/shared/helper_functions.rb +++ b/Library/Homebrew/rubocops/shared/helper_functions.rb @@ -11,8 +11,6 @@ module RuboCop module Cop # Helper functions for cops. - # - # @api private module HelperFunctions include RangeHelp diff --git a/Library/Homebrew/rubocops/shared/on_system_conditionals_helper.rb b/Library/Homebrew/rubocops/shared/on_system_conditionals_helper.rb index 3441c15f32feb3..522e5f1dde0c50 100644 --- a/Library/Homebrew/rubocops/shared/on_system_conditionals_helper.rb +++ b/Library/Homebrew/rubocops/shared/on_system_conditionals_helper.rb @@ -7,8 +7,6 @@ module RuboCop module Cop # This module performs common checks on `on_{system}` blocks in both formulae and casks. - # - # @api private module OnSystemConditionalsHelper extend NodePattern::Macros include HelperFunctions diff --git a/Library/Homebrew/rubocops/shell_commands.rb b/Library/Homebrew/rubocops/shell_commands.rb index 505141ead5c614..537c1be7986d21 100644 --- a/Library/Homebrew/rubocops/shell_commands.rb +++ b/Library/Homebrew/rubocops/shell_commands.rb @@ -45,8 +45,6 @@ module Homebrew SHELL_METACHARACTERS = %W[* ? { } [ ] < > ( ) ~ & | \\ $ ; ' ` " \n #].freeze # This cop makes sure that shell command arguments are separated. - # - # @api private class ShellCommands < Base include HelperFunctions extend AutoCorrector @@ -109,8 +107,6 @@ def on_send(node) end # This cop disallows shell metacharacters in `exec` calls. - # - # @api private class ExecShellMetacharacters < Base include HelperFunctions diff --git a/Library/Homebrew/rubocops/text.rb b/Library/Homebrew/rubocops/text.rb index c14a159655def3..56601d0c174ba0 100644 --- a/Library/Homebrew/rubocops/text.rb +++ b/Library/Homebrew/rubocops/text.rb @@ -7,8 +7,6 @@ module RuboCop module Cop module FormulaAudit # This cop checks for various problems in a formula's source code. - # - # @api private class Text < FormulaCop extend AutoCorrector @@ -107,8 +105,6 @@ def audit_formula(node, _class_node, _parent_class_node, body_node) module FormulaAuditStrict # This cop contains stricter checks for various problems in a formula's source code. - # - # @api private class Text < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? diff --git a/Library/Homebrew/rubocops/urls.rb b/Library/Homebrew/rubocops/urls.rb index 4d60f6707befce..4e388166c27bdd 100644 --- a/Library/Homebrew/rubocops/urls.rb +++ b/Library/Homebrew/rubocops/urls.rb @@ -7,8 +7,6 @@ module RuboCop module Cop module FormulaAudit # This cop audits `url`s and `mirror`s in formulae. - # - # @api private class Urls < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? @@ -265,8 +263,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) end # This cop makes sure that the correct format for PyPI URLs is used. - # - # @api private class PyPiUrls < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? @@ -297,8 +293,6 @@ def get_pypi_url(url) end # This cop makes sure that git URLs have a `revision`. - # - # @api private class GitUrls < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? @@ -321,8 +315,6 @@ def audit_formula(_node, _class_node, _parent_class_node, body_node) module FormulaAuditStrict # This cop makes sure that git URLs have a `tag`. - # - # @api private class GitUrls < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) return if body_node.nil? diff --git a/Library/Homebrew/rubocops/version.rb b/Library/Homebrew/rubocops/version.rb index 3a0c5ccc2046ae..e2ba8069a882b8 100644 --- a/Library/Homebrew/rubocops/version.rb +++ b/Library/Homebrew/rubocops/version.rb @@ -7,8 +7,6 @@ module RuboCop module Cop module FormulaAudit # This cop makes sure that a `version` is in the correct format. - # - # @api private class Version < FormulaCop def audit_formula(_node, _class_node, _parent_class_node, body_node) version_node = find_node_method_by_name(body_node, :version) diff --git a/Library/Homebrew/sandbox.rb b/Library/Homebrew/sandbox.rb index 4aa6126590bd87..c82a572ef36bcc 100644 --- a/Library/Homebrew/sandbox.rb +++ b/Library/Homebrew/sandbox.rb @@ -7,8 +7,6 @@ require "tempfile" # Helper class for running a sub-process inside of a sandboxed environment. -# -# @api private class Sandbox SANDBOX_EXEC = "/usr/bin/sandbox-exec" private_constant :SANDBOX_EXEC diff --git a/Library/Homebrew/search.rb b/Library/Homebrew/search.rb index ffd09da2129286..8c04f4356156df 100644 --- a/Library/Homebrew/search.rb +++ b/Library/Homebrew/search.rb @@ -5,8 +5,6 @@ module Homebrew # Helper module for searching formulae or casks. - # - # @api private module Search def self.query_regexp(query) if (m = query.match(%r{^/(.*)/$})) diff --git a/Library/Homebrew/settings.rb b/Library/Homebrew/settings.rb index e880c5bdf46f58..8a78e72d0a0df2 100644 --- a/Library/Homebrew/settings.rb +++ b/Library/Homebrew/settings.rb @@ -5,8 +5,6 @@ module Homebrew # Helper functions for reading and writing settings. - # - # @api private module Settings def self.read(setting, repo: HOMEBREW_REPOSITORY) return unless (repo/".git/config").exist? diff --git a/Library/Homebrew/simulate_system.rb b/Library/Homebrew/simulate_system.rb index e03987b8261c29..590129993e4c50 100644 --- a/Library/Homebrew/simulate_system.rb +++ b/Library/Homebrew/simulate_system.rb @@ -3,8 +3,6 @@ module Homebrew # Helper module for simulating different system configurations. - # - # @api private class SimulateSystem class << self attr_reader :arch, :os diff --git a/Library/Homebrew/source_location.rb b/Library/Homebrew/source_location.rb index 9b4b4b778933ba..b3671cb5a4802f 100644 --- a/Library/Homebrew/source_location.rb +++ b/Library/Homebrew/source_location.rb @@ -3,8 +3,6 @@ module Homebrew # A location in source code. - # - # @api private class SourceLocation sig { returns(Integer) } attr_reader :line diff --git a/Library/Homebrew/standalone/sorbet.rb b/Library/Homebrew/standalone/sorbet.rb index 85647b6fbe8e7a..aec651361d6f3f 100644 --- a/Library/Homebrew/standalone/sorbet.rb +++ b/Library/Homebrew/standalone/sorbet.rb @@ -9,7 +9,7 @@ # if assured that there is no performance hit from removing this. # There are mechanisms to achieve a middle ground (`default_checked_level`). unless ENV["HOMEBREW_SORBET_RUNTIME"] - # Redefine T.let etc to make the `checked` parameter default to false rather than true. + # Redefine `T.let`, etc. to make the `checked` parameter default to `false` rather than `true`. # @private module TNoChecks def cast(value, type, checked: false) @@ -35,8 +35,7 @@ class << self prepend TNoChecks end - # Redefine T.sig to be noop. - # @private + # Redefine `T.sig` to be a no-op. module Sig def sig(arg0 = nil, &blk); end end diff --git a/Library/Homebrew/style.rb b/Library/Homebrew/style.rb index 69d13d8a1a6fa4..9bc07880cd7c62 100644 --- a/Library/Homebrew/style.rb +++ b/Library/Homebrew/style.rb @@ -7,8 +7,6 @@ module Homebrew # Helper module for running RuboCop. - # - # @api private module Style extend SystemCommand::Mixin diff --git a/Library/Homebrew/system_command.rb b/Library/Homebrew/system_command.rb index 55ec51978990a0..ec4afdd4dfc1c2 100644 --- a/Library/Homebrew/system_command.rb +++ b/Library/Homebrew/system_command.rb @@ -11,8 +11,6 @@ require "utils/timer" # Class for running sub-processes and capturing their output and exit status. -# -# @api private class SystemCommand # Helper functions for calling {SystemCommand.run}. module Mixin diff --git a/Library/Homebrew/system_config.rb b/Library/Homebrew/system_config.rb index 69a218df70229b..c24f2249984f8e 100644 --- a/Library/Homebrew/system_config.rb +++ b/Library/Homebrew/system_config.rb @@ -8,8 +8,6 @@ require "system_command" # Helper module for querying information about the system configuration. -# -# @api private module SystemConfig class << self include SystemCommand::Mixin diff --git a/Library/Homebrew/tap.rb b/Library/Homebrew/tap.rb index b3a799d43c6d32..fb332b7141cca4 100644 --- a/Library/Homebrew/tap.rb +++ b/Library/Homebrew/tap.rb @@ -19,15 +19,24 @@ class Tap TAP_DIRECTORY = (HOMEBREW_LIBRARY/"Taps").freeze HOMEBREW_TAP_CASK_RENAMES_FILE = "cask_renames.json" + private_constant :HOMEBREW_TAP_CASK_RENAMES_FILE HOMEBREW_TAP_FORMULA_RENAMES_FILE = "formula_renames.json" + private_constant :HOMEBREW_TAP_FORMULA_RENAMES_FILE HOMEBREW_TAP_MIGRATIONS_FILE = "tap_migrations.json" + private_constant :HOMEBREW_TAP_MIGRATIONS_FILE HOMEBREW_TAP_AUTOBUMP_FILE = ".github/autobump.txt" + private_constant :HOMEBREW_TAP_AUTOBUMP_FILE HOMEBREW_TAP_PYPI_FORMULA_MAPPINGS_FILE = "pypi_formula_mappings.json" + private_constant :HOMEBREW_TAP_PYPI_FORMULA_MAPPINGS_FILE HOMEBREW_TAP_SYNCED_VERSIONS_FORMULAE_FILE = "synced_versions_formulae.json" + private_constant :HOMEBREW_TAP_SYNCED_VERSIONS_FORMULAE_FILE HOMEBREW_TAP_AUDIT_EXCEPTIONS_DIR = "audit_exceptions" + private_constant :HOMEBREW_TAP_AUDIT_EXCEPTIONS_DIR HOMEBREW_TAP_STYLE_EXCEPTIONS_DIR = "style_exceptions" + private_constant :HOMEBREW_TAP_STYLE_EXCEPTIONS_DIR TAP_MIGRATIONS_STALE_SECONDS = 86400 # 1 day + private_constant :TAP_MIGRATIONS_STALE_SECONDS HOMEBREW_TAP_JSON_FILES = %W[ #{HOMEBREW_TAP_FORMULA_RENAMES_FILE} @@ -41,6 +50,9 @@ class Tap class InvalidNameError < ArgumentError; end + # Fetch a {Tap} by name. + # + # @api public sig { params(user: String, repo: String).returns(Tap) } def self.fetch(user, repo = T.unsafe(nil)) user, repo = user.split("/", 2) if repo.nil? @@ -63,6 +75,9 @@ def self.fetch(user, repo = T.unsafe(nil)) cache.fetch(cache_key) { |key| cache[key] = new(user, repo) } end + # Get a {Tap} from it's path or a path inside of it. + # + # @api public def self.from_path(path) match = File.expand_path(path).match(HOMEBREW_TAP_PATH_REGEX) @@ -73,7 +88,6 @@ def self.from_path(path) fetch(user, repo) end - # @private sig { params(name: String).returns(T.nilable([Tap, String])) } def self.with_formula_name(name) return unless (match = name.match(HOMEBREW_TAP_FORMULA_REGEX)) @@ -89,7 +103,6 @@ def self.with_formula_name(name) [tap, name.downcase] end - # @private sig { params(token: String).returns(T.nilable([Tap, String])) } def self.with_cask_token(token) return unless (match = token.match(HOMEBREW_TAP_CASK_REGEX)) @@ -123,23 +136,38 @@ def self.install_default_cask_tap_if_necessary(force: false) # The user name of this {Tap}. Usually, it's the GitHub username of # this {Tap}'s remote repository. + # + # @api public attr_reader :user # The repository name of this {Tap} without the leading `homebrew-`. + # + # @api public attr_reader :repo # The name of this {Tap}. It combines {#user} and {#repo} with a slash. # {#name} is always in lowercase. # e.g. `user/repo` + # + # @api public attr_reader :name + # Alias for {#name}. + # + # @api public + def to_s = name + # The full name of this {Tap}, including the `homebrew-` prefix. # It combines {#user} and 'homebrew-'-prefixed {#repo} with a slash. # e.g. `user/homebrew-repo` + # + # @api public attr_reader :full_name # The local path to this {Tap}. # e.g. `/usr/local/Library/Taps/user/homebrew-repo` + # + # @api public sig { returns(Pathname) } attr_reader :path @@ -211,6 +239,8 @@ def ensure_installed! # The remote path to this {Tap}. # e.g. `https://github.com/user/homebrew-repo` + # + # @api public def remote return default_remote unless installed? @@ -219,6 +249,8 @@ def remote # The remote repository name of this {Tap}. # e.g. `user/homebrew-repo` + # + # @api public sig { returns(T.nilable(String)) } def remote_repo return unless (remote = self.remote) @@ -234,7 +266,6 @@ def default_remote "https://github.com/#{full_name}" end - # @private sig { returns(String) } def repo_var_suffix @repo_var_suffix ||= path.to_s @@ -243,12 +274,16 @@ def repo_var_suffix .upcase end - # True if this {Tap} is a Git repository. + # Check whether this {Tap} is a Git repository. + # + # @api public def git? git_repo.git_repo? end # Git branch for this {Tap}. + # + # @api public def git_branch raise TapUnavailableError, name unless installed? @@ -256,6 +291,8 @@ def git_branch end # Git HEAD for this {Tap}. + # + # @api public def git_head raise TapUnavailableError, name unless installed? @@ -263,6 +300,8 @@ def git_head end # Time since last git commit for this {Tap}. + # + # @api public def git_last_commit raise TapUnavailableError, name unless installed? @@ -271,6 +310,8 @@ def git_last_commit # The issues URL of this {Tap}. # e.g. `https://github.com/user/homebrew-repo/issues` + # + # @api public sig { returns(T.nilable(String)) } def issues_url return if !official? && custom_remote? @@ -278,16 +319,23 @@ def issues_url "#{default_remote}/issues" end + # Alias for {Tap#name}. + # + # @api public def to_s name end - # True if this {Tap} is an official Homebrew tap. + # Check whether this {Tap} is an official Homebrew tap. + # + # @api public def official? user == "Homebrew" end # Check whether the remote of this {Tap} is a private repository. + # + # @api public sig { returns(T::Boolean) } def private? return @private if defined?(@private) @@ -322,24 +370,24 @@ def config end end - # True if this {Tap} has been installed. + # Check whether this {Tap} is installed. + # + # @api public sig { returns(T::Boolean) } def installed? path.directory? end - # True if this {Tap} is not a full clone. + # Check whether this {Tap} is a shallow clone. def shallow? (path/".git/shallow").exist? end - # @private sig { returns(T::Boolean) } def core_tap? false end - # @private sig { returns(T::Boolean) } def core_cask_tap? false @@ -352,6 +400,8 @@ def core_cask_tap? # @param custom_remote [Boolean] If set, change the tap's remote if already installed. # @param verify [Boolean] If set, verify all the formula, casks and aliases in the tap are valid. # @param force [Boolean] If set, force core and cask taps to install even under API mode. + # + # @api public def install(quiet: false, clone_target: nil, custom_remote: false, verify: false, force: false) require "descriptions" @@ -514,6 +564,8 @@ def fix_remote_configuration(requested_remote: nil, quiet: false) end # Uninstall this {Tap}. + # + # @api public def uninstall(manual: false) require "descriptions" raise TapUnavailableError, name unless installed? @@ -550,7 +602,7 @@ def uninstall(manual: false) Homebrew::Settings.write :untapped, untapped.join(";") end - # True if the {#remote} of {Tap} is customized. + # Check whether the {#remote} of {Tap} is customized. sig { returns(T::Boolean) } def custom_remote? return true unless (remote = self.remote) @@ -559,6 +611,8 @@ def custom_remote? end # Path to the directory of all {Formula} files for this {Tap}. + # + # @api public sig { returns(Pathname) } def formula_dir # Official formulae taps always use this directory, saves time to hardcode. @@ -580,6 +634,8 @@ def new_formula_path(name) end # Path to the directory of all {Cask} files for this {Tap}. + # + # @api public sig { returns(Pathname) } def cask_dir @cask_dir ||= path/"Casks" @@ -631,8 +687,6 @@ def formula_files end # A mapping of {Formula} names to {Formula} file paths. - # - # @private sig { returns(T::Hash[String, Pathname]) } def formula_files_by_name @formula_files_by_name ||= formula_files.each_with_object({}) do |file, hash| @@ -654,8 +708,6 @@ def cask_files end # A mapping of {Cask} tokens to {Cask} file paths. - # - # @private sig { returns(T::Hash[String, Pathname]) } def cask_files_by_name @cask_files_by_name ||= cask_files.each_with_object({}) do |file, hash| @@ -666,16 +718,16 @@ def cask_files_by_name end end - # returns true if the file has a Ruby extension + # Check whether the file has a Ruby extension. + # # @private sig { params(file: Pathname).returns(T::Boolean) } def ruby_file?(file) file.extname == ".rb" end - # returns true if given path would present a {Formula} file in this {Tap}. - # accepts both absolute path and relative path (relative to this {Tap}'s path) - # @private + # Check whether the given path would present a {Formula} file in this {Tap}. + # Accepts either an absolute path or a path relative to this {Tap}'s path. sig { params(file: T.any(String, Pathname)).returns(T::Boolean) } def formula_file?(file) file = Pathname.new(file) unless file.is_a? Pathname @@ -686,9 +738,8 @@ def formula_file?(file) file.to_s.start_with?("#{formula_dir}/") end - # returns true if given path would present a {Cask} file in this {Tap}. - # accepts both absolute path and relative path (relative to this {Tap}'s path) - # @private + # Check whether the given path would present a {Cask} file in this {Tap}. + # Accepts either an absolute path or a path relative to this {Tap}'s path. sig { params(file: T.any(String, Pathname)).returns(T::Boolean) } def cask_file?(file) file = Pathname.new(file) unless file.is_a? Pathname @@ -705,7 +756,6 @@ def formula_names end # A hash of all {Formula} name prefixes to versioned {Formula} in this {Tap}. - # @private sig { returns(T::Hash[String, T::Array[String]]) } def prefix_to_versioned_formulae_names @prefix_to_versioned_formulae_names ||= formula_names @@ -721,30 +771,25 @@ def cask_tokens @cask_tokens ||= cask_files.map { formula_file_to_name(_1) } end - # path to the directory of all alias files for this {Tap}. - # @private + # Path to the directory of all alias files for this {Tap}. sig { returns(Pathname) } def alias_dir @alias_dir ||= path/"Aliases" end - # an array of all alias files of this {Tap}. - # @private + # An array of all alias files of this {Tap}. sig { returns(T::Array[Pathname]) } def alias_files @alias_files ||= Pathname.glob("#{alias_dir}/*").select(&:file?) end - # an array of all aliases of this {Tap}. - # @private + # An array of all aliases of this {Tap}. sig { returns(T::Array[String]) } def aliases @aliases ||= alias_table.keys end # Mapping from aliases to formula names. - # - # @private sig { returns(T::Hash[String, String]) } def alias_table @alias_table ||= alias_files.each_with_object({}) do |alias_file, alias_table| @@ -753,8 +798,6 @@ def alias_table end # Mapping from formula names to aliases. - # - # @private sig { returns(T::Hash[String, T::Array[String]]) } def alias_reverse_table @alias_reverse_table ||= alias_table.each_with_object({}) do |(alias_name, formula_name), alias_reverse_table| @@ -814,8 +857,6 @@ def cask_renames end # Mapping from new to old cask tokens. Reverse of {#cask_renames}. - # - # @private sig { returns(T::Hash[String, T::Array[String]]) } def cask_reverse_renames @cask_reverse_renames ||= cask_renames.each_with_object({}) do |(old_name, new_name), hash| @@ -835,8 +876,6 @@ def formula_renames end # Mapping from new to old formula names. Reverse of {#formula_renames}. - # - # @private sig { returns(T::Hash[String, T::Array[String]]) } def formula_reverse_renames @formula_reverse_renames ||= formula_renames.each_with_object({}) do |(old_name, new_name), hash| @@ -924,7 +963,6 @@ def synced_versions_formulae end end - # @private sig { returns(T::Boolean) } def should_report_analytics? installed? && !private? @@ -943,6 +981,8 @@ def hash end # All locally installed taps. + # + # @api public sig { returns(T::Array[Tap]) } def self.installed cache[:installed] ||= if TAP_DIRECTORY.directory? @@ -953,6 +993,8 @@ def self.installed end # All locally installed and core taps. Core taps might not be installed locally when using the API. + # + # @api public sig { returns(T::Array[Tap]) } def self.all cache[:all] ||= begin @@ -965,12 +1007,29 @@ def self.all end end + # Enumerate all available {Tap}s. + # + # @api public def self.each(&block) - if Homebrew::EnvConfig.no_install_from_api? - installed.each(&block) + return to_enum unless block + + installed_taps = if TAP_DIRECTORY.directory? + TAP_DIRECTORY.subdirs + .flat_map(&:subdirs) + .map(&method(:from_path)) else - all.each(&block) + [] end + + available_taps = if Homebrew::EnvConfig.no_install_from_api? + installed_taps + else + default_taps = T.let([CoreTap.instance], T::Array[Tap]) + default_taps << CoreCaskTap.instance if OS.mac? # rubocop:disable Homebrew/MoveToExtendOS + installed_taps + default_taps + end.sort_by(&:name).uniq + + available_taps.each(&block) end # An array of all installed {Tap} names. @@ -993,13 +1052,11 @@ def self.untapped_official_taps Homebrew::Settings.read(:untapped)&.split(";") || [] end - # @private sig { params(file: Pathname).returns(String) } def formula_file_to_name(file) "#{name}/#{file.basename(".rb")}" end - # @private sig { params(file: Pathname).returns(String) } def alias_file_to_name(file) "#{name}/#{file.basename}" @@ -1078,7 +1135,6 @@ def self.ensure_installed! instance.ensure_installed! end - # @private sig { params(file: Pathname).returns(String) } def formula_file_to_name(file) file.basename(".rb").to_s @@ -1131,7 +1187,6 @@ def install(quiet: false, clone_target: nil, super(quiet:, clone_target: remote, custom_remote:, force:) end - # @private sig { params(manual: T::Boolean).void } def uninstall(manual: false) raise "Tap#uninstall is not available for CoreTap" if Homebrew::EnvConfig.no_install_from_api? @@ -1139,19 +1194,16 @@ def uninstall(manual: false) super end - # @private sig { returns(T::Boolean) } def core_tap? true end - # @private sig { returns(T::Boolean) } def linuxbrew_core? remote_repo.to_s.end_with?("/linuxbrew-core") || remote_repo == "Linuxbrew/homebrew-core" end - # @private sig { returns(Pathname) } def formula_dir @formula_dir ||= begin @@ -1173,7 +1225,6 @@ def new_formula_path(name) formula_dir/formula_subdir/"#{name.downcase}.rb" end - # @private sig { returns(Pathname) } def alias_dir @alias_dir ||= begin @@ -1182,7 +1233,6 @@ def alias_dir end end - # @private sig { returns(T::Hash[String, String]) } def formula_renames @formula_renames ||= if Homebrew::EnvConfig.no_install_from_api? @@ -1193,7 +1243,6 @@ def formula_renames end end - # @private sig { returns(Hash) } def tap_migrations @tap_migrations ||= if Homebrew::EnvConfig.no_install_from_api? @@ -1208,7 +1257,6 @@ def tap_migrations end end - # @private sig { returns(T::Array[String]) } def autobump @autobump ||= begin @@ -1217,7 +1265,6 @@ def autobump end end - # @private sig { returns(Hash) } def audit_exceptions @audit_exceptions ||= begin @@ -1226,7 +1273,6 @@ def audit_exceptions end end - # @private sig { returns(Hash) } def style_exceptions @style_exceptions ||= begin @@ -1235,7 +1281,6 @@ def style_exceptions end end - # @private sig { returns(Hash) } def pypi_formula_mappings @pypi_formula_mappings ||= begin @@ -1244,7 +1289,6 @@ def pypi_formula_mappings end end - # @private sig { returns(T::Array[T::Array[String]]) } def synced_versions_formulae @synced_versions_formulae ||= begin @@ -1253,13 +1297,11 @@ def synced_versions_formulae end end - # @private sig { params(file: Pathname).returns(String) } def alias_file_to_name(file) file.basename.to_s end - # @private sig { returns(T::Hash[String, String]) } def alias_table @alias_table ||= if Homebrew::EnvConfig.no_install_from_api? @@ -1269,7 +1311,6 @@ def alias_table end end - # @private sig { returns(T::Array[Pathname]) } def formula_files return super if Homebrew::EnvConfig.no_install_from_api? @@ -1277,7 +1318,6 @@ def formula_files formula_files_by_name.values end - # @private sig { returns(T::Array[String]) } def formula_names return super if Homebrew::EnvConfig.no_install_from_api? @@ -1285,7 +1325,6 @@ def formula_names Homebrew::API::Formula.all_formulae.keys end - # @private sig { returns(T::Hash[String, Pathname]) } def formula_files_by_name return super if Homebrew::EnvConfig.no_install_from_api? @@ -1329,7 +1368,6 @@ def initialize super "Homebrew", "cask" end - # @private sig { override.returns(T::Boolean) } def core_cask_tap? true @@ -1355,7 +1393,6 @@ def cask_tokens Homebrew::API::Cask.all_casks.keys end - # @private sig { override.returns(T::Hash[String, Pathname]) } def cask_files_by_name return super if Homebrew::EnvConfig.no_install_from_api? diff --git a/Library/Homebrew/tap_auditor.rb b/Library/Homebrew/tap_auditor.rb index 2e7c3cd08059bc..33a577101969b9 100644 --- a/Library/Homebrew/tap_auditor.rb +++ b/Library/Homebrew/tap_auditor.rb @@ -3,8 +3,6 @@ module Homebrew # Auditor for checking common violations in {Tap}s. - # - # @api private class TapAuditor attr_reader :name, :path, :formula_names, :formula_aliases, :formula_renames, :cask_tokens, :tap_audit_exceptions, :tap_style_exceptions, :tap_pypi_formula_mappings, :problems diff --git a/Library/Homebrew/uninstall.rb b/Library/Homebrew/uninstall.rb index b3e807b6009782..543e65c376ad20 100644 --- a/Library/Homebrew/uninstall.rb +++ b/Library/Homebrew/uninstall.rb @@ -5,8 +5,6 @@ module Homebrew # Helper module for uninstalling kegs. - # - # @api private module Uninstall def self.uninstall_kegs(kegs_by_rack, casks: [], force: false, ignore_dependencies: false, named_args: []) handle_unsatisfied_dependents(kegs_by_rack, @@ -117,7 +115,6 @@ def self.check_for_dependents(kegs, casks: [], named_args: []) true end - # @api private class DependentsMessage attr_reader :reqs, :deps, :named_args @@ -139,7 +136,6 @@ def are_required_by_deps end end - # @api private class DeveloperDependentsMessage < DependentsMessage def output opoo <<~EOS @@ -150,7 +146,6 @@ def output end end - # @api private class NondeveloperDependentsMessage < DependentsMessage def output ofail <<~EOS diff --git a/Library/Homebrew/unpack_strategy.rb b/Library/Homebrew/unpack_strategy.rb index 3ce46060d3317b..74e49473cbcaa6 100644 --- a/Library/Homebrew/unpack_strategy.rb +++ b/Library/Homebrew/unpack_strategy.rb @@ -4,8 +4,6 @@ require "system_command" # Module containing all available strategies for unpacking archives. -# -# @api private module UnpackStrategy extend T::Helpers diff --git a/Library/Homebrew/unversioned_cask_checker.rb b/Library/Homebrew/unversioned_cask_checker.rb index aa207460c4cb4e..241e63348d6248 100644 --- a/Library/Homebrew/unversioned_cask_checker.rb +++ b/Library/Homebrew/unversioned_cask_checker.rb @@ -9,8 +9,6 @@ module Homebrew # Check unversioned casks for updates by extracting their # contents and guessing the version from contained files. - # - # @api private class UnversionedCaskChecker include SystemCommand::Mixin diff --git a/Library/Homebrew/upgrade.rb b/Library/Homebrew/upgrade.rb index 4bf5d5c977296f..068a3b66d23440 100644 --- a/Library/Homebrew/upgrade.rb +++ b/Library/Homebrew/upgrade.rb @@ -10,8 +10,6 @@ module Homebrew # Helper functions for upgrading formulae. - # - # @api private module Upgrade module_function diff --git a/Library/Homebrew/url.rb b/Library/Homebrew/url.rb index 0a029e686b909c..adbff352fc531e 100644 --- a/Library/Homebrew/url.rb +++ b/Library/Homebrew/url.rb @@ -4,7 +4,6 @@ require "download_strategy" require "version" -# @api private class URL attr_reader :specs, :using diff --git a/Library/Homebrew/utils/analytics.rb b/Library/Homebrew/utils/analytics.rb index 51bdebaa455f96..cff688ccee7455 100644 --- a/Library/Homebrew/utils/analytics.rb +++ b/Library/Homebrew/utils/analytics.rb @@ -8,8 +8,6 @@ module Utils # Helper module for fetching and reporting analytics data. - # - # @api private module Analytics INFLUX_BUCKET = "analytics" INFLUX_TOKEN = "iVdsgJ_OjvTYGAA79gOfWlA_fX0QCuj4eYUNdb-qVUTrC3tp3JTWCADVNE9HxV0kp2ZjIK9tuthy_teX4szr9A==" diff --git a/Library/Homebrew/utils/ast.rb b/Library/Homebrew/utils/ast.rb index 6000a8a8b0def3..7103fb300b8fa8 100644 --- a/Library/Homebrew/utils/ast.rb +++ b/Library/Homebrew/utils/ast.rb @@ -6,8 +6,6 @@ module Utils # Helper functions for editing Ruby files. - # - # @api private module AST Node = RuboCop::AST::Node SendNode = RuboCop::AST::SendNode @@ -74,8 +72,6 @@ def call_node_match?(node, name:, type: nil) end # Helper class for editing formulae. - # - # @api private class FormulaAST extend Forwardable include AST diff --git a/Library/Homebrew/utils/bottles.rb b/Library/Homebrew/utils/bottles.rb index 20f1f965fe7919..078372695f8824 100644 --- a/Library/Homebrew/utils/bottles.rb +++ b/Library/Homebrew/utils/bottles.rb @@ -5,8 +5,6 @@ module Utils # Helper functions for bottles. - # - # @api private module Bottles class << self # Gets the tag for the running OS. diff --git a/Library/Homebrew/utils/curl.rb b/Library/Homebrew/utils/curl.rb index eae1793a08e529..80cb9083851eeb 100644 --- a/Library/Homebrew/utils/curl.rb +++ b/Library/Homebrew/utils/curl.rb @@ -8,8 +8,6 @@ module Utils # Helper function for interacting with `curl`. - # - # @api private module Curl include SystemCommand::Mixin extend SystemCommand::Mixin diff --git a/Library/Homebrew/utils/formatter.rb b/Library/Homebrew/utils/formatter.rb index 50f7569b3f77d6..4d1c1e9baf4073 100644 --- a/Library/Homebrew/utils/formatter.rb +++ b/Library/Homebrew/utils/formatter.rb @@ -4,8 +4,6 @@ require "utils/tty" # Helper module for formatting output. -# -# @api private module Formatter COMMAND_DESC_WIDTH = 80 OPTION_DESC_WIDTH = 45 diff --git a/Library/Homebrew/utils/gems.rb b/Library/Homebrew/utils/gems.rb index eec1dbe7848a84..949282b44f9553 100644 --- a/Library/Homebrew/utils/gems.rb +++ b/Library/Homebrew/utils/gems.rb @@ -32,17 +32,16 @@ module Homebrew module_function - # @api private def gemfile File.join(ENV.fetch("HOMEBREW_LIBRARY"), "Homebrew", "Gemfile") end + private_class_method :gemfile - # @api private def bundler_definition @bundler_definition ||= Bundler::Definition.build(Bundler.default_gemfile, Bundler.default_lockfile, false) end + private_class_method :bundler_definition - # @api private def valid_gem_groups install_bundler! require "bundler" @@ -54,6 +53,7 @@ def valid_gem_groups groups.map(&:to_s) end end + private_class_method :valid_gem_groups def ruby_bindir "#{RbConfig::CONFIG["prefix"]}/bin" @@ -157,6 +157,7 @@ def find_in_path(executable) File.executable?(File.join(path, executable)) end end + private_class_method :find_in_path def install_bundler! old_bundler_version = ENV.fetch("BUNDLER_VERSION", nil) @@ -181,6 +182,7 @@ def user_gem_groups [] end end + private_class_method :user_gem_groups def write_user_gem_groups(groups) return if @user_gem_groups == groups && GEM_GROUPS_FILE.exist? @@ -203,6 +205,7 @@ def write_user_gem_groups(groups) @user_gem_groups = groups end + private_class_method :write_user_gem_groups def forget_user_gem_groups! GEM_GROUPS_FILE.truncate(0) if GEM_GROUPS_FILE.exist? @@ -216,6 +219,7 @@ def user_vendor_version 0 end end + private_class_method :user_vendor_version def install_bundler_gems!(only_warn_on_failure: false, setup_path: true, groups: []) old_path = ENV.fetch("PATH", nil) diff --git a/Library/Homebrew/utils/git.rb b/Library/Homebrew/utils/git.rb index 7027ee026e3f03..29edb1cc153eed 100644 --- a/Library/Homebrew/utils/git.rb +++ b/Library/Homebrew/utils/git.rb @@ -7,7 +7,6 @@ module Utils # Helper functions for querying Git information. # # @see GitRepository - # @api private module Git extend SystemCommand::Mixin diff --git a/Library/Homebrew/utils/github.rb b/Library/Homebrew/utils/github.rb index d2cde79847ad53..9538e82689c9b6 100644 --- a/Library/Homebrew/utils/github.rb +++ b/Library/Homebrew/utils/github.rb @@ -7,9 +7,9 @@ require "system_command" -# Wrapper functions for the GitHub API. +# A module that interfaces with GitHub, code like PAT scopes, credential handling and API errors. # -# @api private +# @api internal module GitHub extend SystemCommand::Mixin diff --git a/Library/Homebrew/utils/github/actions.rb b/Library/Homebrew/utils/github/actions.rb index b6e3d6b768f5b5..9e20bef10bfedb 100644 --- a/Library/Homebrew/utils/github/actions.rb +++ b/Library/Homebrew/utils/github/actions.rb @@ -7,7 +7,7 @@ module GitHub # Helper functions for interacting with GitHub Actions. # - # @api private + # @api internal module Actions sig { params(string: String).returns(String) } def self.escape(string) diff --git a/Library/Homebrew/utils/github/api.rb b/Library/Homebrew/utils/github/api.rb index f783fbab931617..46e639a1e9772f 100644 --- a/Library/Homebrew/utils/github/api.rb +++ b/Library/Homebrew/utils/github/api.rb @@ -6,7 +6,6 @@ require "utils/shell" require "utils/formatter" -# A module that interfaces with GitHub, code like PAT scopes, credential handling and API errors. module GitHub def self.pat_blurb(scopes = ALL_SCOPES) <<~EOS @@ -20,18 +19,23 @@ def self.pat_blurb(scopes = ALL_SCOPES) API_URL = "https://api.github.com" API_MAX_PAGES = 50 + private_constant :API_MAX_PAGES API_MAX_ITEMS = 5000 + private_constant :API_MAX_ITEMS PAGINATE_RETRY_COUNT = 3 + private_constant :PAGINATE_RETRY_COUNT CREATE_GIST_SCOPES = ["gist"].freeze CREATE_ISSUE_FORK_OR_PR_SCOPES = ["repo"].freeze CREATE_WORKFLOW_SCOPES = ["workflow"].freeze ALL_SCOPES = (CREATE_GIST_SCOPES + CREATE_ISSUE_FORK_OR_PR_SCOPES + CREATE_WORKFLOW_SCOPES).freeze + private_constant :ALL_SCOPES GITHUB_PERSONAL_ACCESS_TOKEN_REGEX = /^(?:[a-f0-9]{40}|(?:gh[pousr]|github_pat)_\w{36,251})$/ + private_constant :GITHUB_PERSONAL_ACCESS_TOKEN_REGEX - # Helper functions to access the GitHub API. + # Helper functions for accessing the GitHub API. # - # @api private + # @api internal module API extend SystemCommand::Mixin diff --git a/Library/Homebrew/utils/github/artifacts.rb b/Library/Homebrew/utils/github/artifacts.rb index 7baaa6f5742720..70290e579ecdde 100644 --- a/Library/Homebrew/utils/github/artifacts.rb +++ b/Library/Homebrew/utils/github/artifacts.rb @@ -9,8 +9,6 @@ module GitHub # # @param url [String] URL to download from # @param artifact_id [String] a value that uniquely identifies the downloaded artifact - # - # @api private sig { params(url: String, artifact_id: String).void } def self.download_artifact(url, artifact_id) raise API::MissingAuthenticationError if API.credentials == :none @@ -25,8 +23,6 @@ def self.download_artifact(url, artifact_id) end # Strategy for downloading an artifact from GitHub Actions. -# -# @api private class GitHubArtifactDownloadStrategy < AbstractFileDownloadStrategy def initialize(url, artifact_id, token:) super(url, "artifact", artifact_id) diff --git a/Library/Homebrew/utils/inreplace.rb b/Library/Homebrew/utils/inreplace.rb index 648aebeb93632c..4031fa9c2d4b7f 100644 --- a/Library/Homebrew/utils/inreplace.rb +++ b/Library/Homebrew/utils/inreplace.rb @@ -5,8 +5,6 @@ module Utils # Helper functions for replacing text in files in-place. - # - # @api private module Inreplace # Error during text replacement. class Error < RuntimeError @@ -73,7 +71,6 @@ def self.inreplace(paths, before = nil, after = nil, audit_result: true, &block) raise Utils::Inreplace::Error, errors if errors.present? end - # @api private def self.inreplace_pairs(path, replacement_pairs, read_only_run: false, silent: false) str = File.binread(path) contents = StringInreplaceExtension.new(str) diff --git a/Library/Homebrew/utils/link.rb b/Library/Homebrew/utils/link.rb index d166878bc33226..09e56d2696cf7f 100644 --- a/Library/Homebrew/utils/link.rb +++ b/Library/Homebrew/utils/link.rb @@ -3,8 +3,6 @@ module Utils # Helper functions for creating symlinks. - # - # @api private module Link def self.link_src_dst_dirs(src_dir, dst_dir, command, link_dir: false) return unless src_dir.exist? diff --git a/Library/Homebrew/utils/pypi.rb b/Library/Homebrew/utils/pypi.rb index bef4322792d775..d6a6102bd83aeb 100644 --- a/Library/Homebrew/utils/pypi.rb +++ b/Library/Homebrew/utils/pypi.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true # Helper functions for updating PyPI resources. -# -# @api private module PyPI PYTHONHOSTED_URL_PREFIX = "https://files.pythonhosted.org/packages/" private_constant :PYTHONHOSTED_URL_PREFIX @@ -11,7 +9,6 @@ module PyPI # Represents a Python package. # This package can be a PyPI package (either by name/version or PyPI distribution URL), # or it can be a non-PyPI URL. - # @api private class Package sig { params(package_string: String, is_url: T::Boolean, python_name: String).void } def initialize(package_string, is_url: false, python_name: "python") diff --git a/Library/Homebrew/utils/repology.rb b/Library/Homebrew/utils/repology.rb index f9a05c623e82c9..62095821d68003 100644 --- a/Library/Homebrew/utils/repology.rb +++ b/Library/Homebrew/utils/repology.rb @@ -4,8 +4,6 @@ require "utils/curl" # Repology API client. -# -# @api private module Repology HOMEBREW_CORE = "homebrew" HOMEBREW_CASK = "homebrew_casks" diff --git a/Library/Homebrew/utils/shared_audits.rb b/Library/Homebrew/utils/shared_audits.rb index 5e4fbb79a097fb..3329ea1797fb4a 100644 --- a/Library/Homebrew/utils/shared_audits.rb +++ b/Library/Homebrew/utils/shared_audits.rb @@ -5,8 +5,6 @@ require "utils/github/api" # Auditing functions for rules common to both casks and formulae. -# -# @api private module SharedAudits URL_TYPE_HOMEPAGE = "homepage URL" diff --git a/Library/Homebrew/utils/shebang.rb b/Library/Homebrew/utils/shebang.rb index 95daadcd6d6a2d..34d2356672b235 100644 --- a/Library/Homebrew/utils/shebang.rb +++ b/Library/Homebrew/utils/shebang.rb @@ -3,14 +3,10 @@ module Utils # Helper functions for manipulating shebang lines. - # - # @api private module Shebang module_function # Specification on how to rewrite a given shebang. - # - # @api private class RewriteInfo attr_reader :regex, :max_length, :replacement diff --git a/Library/Homebrew/utils/spdx.rb b/Library/Homebrew/utils/spdx.rb index 8849971e713e3f..f44aa54a8ba69d 100644 --- a/Library/Homebrew/utils/spdx.rb +++ b/Library/Homebrew/utils/spdx.rb @@ -5,8 +5,6 @@ require "utils/github" # Helper module for updating SPDX license data. -# -# @api private module SPDX module_function diff --git a/Library/Homebrew/utils/string_inreplace_extension.rb b/Library/Homebrew/utils/string_inreplace_extension.rb index 4c4d4917d46c08..fffaf771df9309 100644 --- a/Library/Homebrew/utils/string_inreplace_extension.rb +++ b/Library/Homebrew/utils/string_inreplace_extension.rb @@ -2,8 +2,6 @@ # frozen_string_literal: true # Used by the `inreplace` function (in `utils.rb`). -# -# @api private class StringInreplaceExtension sig { returns(T::Array[String]) } attr_accessor :errors diff --git a/Library/Homebrew/utils/svn.rb b/Library/Homebrew/utils/svn.rb index f45e49b3d0af13..93f6b100a976d5 100644 --- a/Library/Homebrew/utils/svn.rb +++ b/Library/Homebrew/utils/svn.rb @@ -5,8 +5,6 @@ module Utils # Helper functions for querying SVN information. - # - # @api private module Svn class << self include SystemCommand::Mixin diff --git a/Library/Homebrew/utils/tar.rb b/Library/Homebrew/utils/tar.rb index ab7b411f5eb618..bf4df5e6649433 100644 --- a/Library/Homebrew/utils/tar.rb +++ b/Library/Homebrew/utils/tar.rb @@ -5,8 +5,6 @@ module Utils # Helper functions for interacting with tar files. - # - # @api private module Tar class << self include SystemCommand::Mixin diff --git a/Library/Homebrew/utils/tty.rb b/Library/Homebrew/utils/tty.rb index 4897c92fb3274b..637a90e6d30fa6 100644 --- a/Library/Homebrew/utils/tty.rb +++ b/Library/Homebrew/utils/tty.rb @@ -4,8 +4,6 @@ require "env_config" # Various helper functions for interacting with TTYs. -# -# @api private module Tty @stream = $stdout diff --git a/Library/Homebrew/utils/user.rb b/Library/Homebrew/utils/user.rb index cb758ef47ed17d..09be3d770774e0 100644 --- a/Library/Homebrew/utils/user.rb +++ b/Library/Homebrew/utils/user.rb @@ -7,8 +7,6 @@ require "system_command" # A system user. -# -# @api private class User < SimpleDelegator include SystemCommand::Mixin diff --git a/Library/Homebrew/version.rb b/Library/Homebrew/version.rb index d1b531b9ad8377..3534ba9343ee42 100644 --- a/Library/Homebrew/version.rb +++ b/Library/Homebrew/version.rb @@ -5,8 +5,6 @@ require "version/parser" # A formula's version. -# -# @api private class Version include Comparable diff --git a/Library/Homebrew/version/parser.rb b/Library/Homebrew/version/parser.rb index 8c7dd9f561c546..76732dd92bf598 100644 --- a/Library/Homebrew/version/parser.rb +++ b/Library/Homebrew/version/parser.rb @@ -2,7 +2,6 @@ # frozen_string_literal: true class Version - # @api private class Parser extend T::Helpers abstract! @@ -11,7 +10,6 @@ class Parser def parse(spec); end end - # @api private class RegexParser < Parser extend T::Helpers abstract! @@ -39,7 +37,6 @@ def parse(spec) def self.process_spec(spec); end end - # @api private class UrlParser < RegexParser sig { override.params(spec: Pathname).returns(String) } def self.process_spec(spec) @@ -47,7 +44,6 @@ def self.process_spec(spec) end end - # @api private class StemParser < RegexParser SOURCEFORGE_DOWNLOAD_REGEX = %r{(?:sourceforge\.net|sf\.net)/.*/download$} NO_FILE_EXTENSION_REGEX = /\.[^a-zA-Z]+$/ diff --git a/Library/Homebrew/warnings.rb b/Library/Homebrew/warnings.rb index 28387659a8d07a..94f06292907953 100644 --- a/Library/Homebrew/warnings.rb +++ b/Library/Homebrew/warnings.rb @@ -4,8 +4,6 @@ require "warning" # Helper module for handling warnings. -# -# @api private module Warnings COMMON_WARNINGS = { parser_syntax: [ diff --git a/Library/Homebrew/yard/docstring_parser.rb b/Library/Homebrew/yard/docstring_parser.rb new file mode 100644 index 00000000000000..739916fbfdf07d --- /dev/null +++ b/Library/Homebrew/yard/docstring_parser.rb @@ -0,0 +1,24 @@ +# typed: true +# frozen_string_literal: true + +# from https://github.com/lsegal/yard/issues/484#issuecomment-442586899 +module Homebrew + module YARD + class DocstringParser < ::YARD::DocstringParser + def parse_content(content) + # Ignore non-documentation comments. + content = content&.sub(/(\A(typed|.*rubocop)|TODO|FIXME):.*/m, "") + + content = super(content) + + # 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) } + + content + end + end + end +end + +YARD::Docstring.default_parser = Homebrew::YARD::DocstringParser diff --git a/Library/Homebrew/yard/ignore_directives.rb b/Library/Homebrew/yard/ignore_directives.rb deleted file mode 100644 index ecc616d037af57..00000000000000 --- a/Library/Homebrew/yard/ignore_directives.rb +++ /dev/null @@ -1,11 +0,0 @@ -# typed: true -# frozen_string_literal: true - -# from https://github.com/lsegal/yard/issues/484#issuecomment-442586899 -class IgnoreDirectiveDocstringParser < YARD::DocstringParser - def parse_content(content) - super(content&.sub(/(\A(typed|.*rubocop)|TODO):.*/m, "")) - end -end - -YARD::Docstring.default_parser = IgnoreDirectiveDocstringParser