diff --git a/Library/.rubocop_cask.yml b/Library/.rubocop_cask.yml
index cc6ccf9a5f5552e8b05cc0bc4495a696f04f5f00..e4c4939a3859f6f83c780f8d50f232d50de83722 100644
--- a/Library/.rubocop_cask.yml
+++ b/Library/.rubocop_cask.yml
@@ -27,5 +27,9 @@ Cask/StanzaOrder:
# don't want these for casks but re-enabled for Library/Homebrew
Style/FrozenStringLiteralComment:
Enabled: false
+
+Style/Documentation:
+ Enabled: false
+
Metrics/BlockLength:
Enabled: false
diff --git a/Library/Homebrew/.rubocop.yml b/Library/Homebrew/.rubocop.yml
index d517069b811461d945654e4b5372abbc80bd0fdc..e280f0f62facb5d168872acdadfd5713f62a31b6 100644
--- a/Library/Homebrew/.rubocop.yml
+++ b/Library/Homebrew/.rubocop.yml
@@ -1,4 +1,6 @@
-inherit_from: ../.rubocop_rspec.yml
+inherit_from:
+ - ../.rubocop_rspec.yml
+ - .rubocop_todo.yml
AllCops:
Include:
@@ -105,12 +107,6 @@ Naming/MethodParameterName:
Style/AccessModifierDeclarations:
Enabled: false
-# make rspec formatting more flexible
-Style/BlockDelimiters:
- Exclude:
- - '**/*_spec.rb'
- - '**/shared_examples/**/*.rb'
-
# don't group nicely documented or private attr_readers
Style/AccessorGrouping:
Exclude:
@@ -121,11 +117,16 @@ Style/AccessorGrouping:
- 'system_command.rb'
- 'tap.rb'
+# make rspec formatting more flexible
+Style/BlockDelimiters:
+ Exclude:
+ - '**/*_spec.rb'
+ - '**/shared_examples/**/*.rb'
+
# document our public APIs
Style/Documentation:
Enabled: true
- Include:
- - 'formula.rb'
+
Style/DocumentationMethod:
Enabled: true
Include:
diff --git a/Library/Homebrew/.rubocop_todo.yml b/Library/Homebrew/.rubocop_todo.yml
new file mode 100644
index 0000000000000000000000000000000000000000..a74f62002a71a8ddb995d26af0759c81d61ba1cf
--- /dev/null
+++ b/Library/Homebrew/.rubocop_todo.yml
@@ -0,0 +1,31 @@
+Style/Documentation:
+ Exclude:
+ - 'compat/**/*.rb'
+ - 'extend/**/*.rb'
+ - 'cmd/**/*.rb'
+ - 'dev-cmd/**/*.rb'
+ - 'test/**/*.rb'
+ - 'cask/macos.rb'
+ - 'cli/args.rb'
+ - 'cli/parser.rb'
+ - 'download_strategy.rb'
+ - 'global.rb'
+ - 'keg_relocate.rb'
+ - 'os/linux/global.rb'
+ - 'os/mac/architecture_list.rb'
+ - 'os/mac/keg.rb'
+ - 'reinstall.rb'
+ - 'software_spec.rb'
+ - 'upgrade.rb'
+ - 'utils.rb'
+ - 'utils/fork.rb'
+ - 'utils/gems.rb'
+ - 'utils/notability.rb'
+ - 'utils/popen.rb'
+ - 'utils/pypi.rb'
+ - 'utils/shebang.rb'
+ - 'utils/shell.rb'
+ - 'utils/spdx.rb'
+ - 'utils/livecheck_formula.rb'
+ - 'utils/repology.rb'
+ - 'version.rb'
diff --git a/Library/Homebrew/PATH.rb b/Library/Homebrew/PATH.rb
index 4f46be178ab84a6bae9731ed6bd61a3b5155a877..ac9f408a93ef0e498c436e64e94aa4cd490e8437 100644
--- a/Library/Homebrew/PATH.rb
+++ b/Library/Homebrew/PATH.rb
@@ -1,5 +1,8 @@
# frozen_string_literal: true
+# Represention of a `*PATH` environment variable.
+#
+# @api private
class PATH
include Enumerable
extend Forwardable
diff --git a/Library/Homebrew/bintray.rb b/Library/Homebrew/bintray.rb
index 5d4b05f36acd5a6a886cd5befebedd139f0c971f..26b9583184591a534dade6cd7ffb2d7e0e08fc57 100644
--- a/Library/Homebrew/bintray.rb
+++ b/Library/Homebrew/bintray.rb
@@ -3,6 +3,9 @@
require "utils/curl"
require "json"
+# Bintray API client.
+#
+# @api private
class Bintray
include Context
diff --git a/Library/Homebrew/build.rb b/Library/Homebrew/build.rb
index 42079473d2a373803768a8c7e432f3e5ed0939e2..a5e374018494e9712092787040a4e711d40c346c 100644
--- a/Library/Homebrew/build.rb
+++ b/Library/Homebrew/build.rb
@@ -15,6 +15,9 @@ require "fcntl"
require "socket"
require "cmd/install"
+# A formula build.
+#
+# @api private
class Build
attr_reader :formula, :deps, :reqs, :args
diff --git a/Library/Homebrew/build_options.rb b/Library/Homebrew/build_options.rb
index fc81bb82182e61f1a67343e666ca3a69e50f4925..be0da2a8efe5a779b30e9691ef0f439c8f0e379b 100644
--- a/Library/Homebrew/build_options.rb
+++ b/Library/Homebrew/build_options.rb
@@ -1,5 +1,8 @@
# frozen_string_literal: true
+# Options for a formula build.
+#
+# @api private
class BuildOptions
# @private
def initialize(args, options)
diff --git a/Library/Homebrew/cask/artifact.rb b/Library/Homebrew/cask/artifact.rb
index 6b5ca20d20bf000faf53479244ce96bde39c7ed5..a86b3232eddd1ddccf1c6f66f6d022451a187716 100644
--- a/Library/Homebrew/cask/artifact.rb
+++ b/Library/Homebrew/cask/artifact.rb
@@ -27,6 +27,9 @@ require "cask/artifact/uninstall"
require "cask/artifact/zap"
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 4d3f86d85a6457a2bf16aab6cc1d745289739e1e..84275ec58a530fdf63148d3e053de0708c630ab2 100644
--- a/Library/Homebrew/cask/artifact/abstract_artifact.rb
+++ b/Library/Homebrew/cask/artifact/abstract_artifact.rb
@@ -2,6 +2,9 @@
module Cask
module Artifact
+ # Abstract superclass for all artifacts.
+ #
+ # @api private
class AbstractArtifact
include Comparable
extend Predicable
diff --git a/Library/Homebrew/cask/artifact/abstract_flight_block.rb b/Library/Homebrew/cask/artifact/abstract_flight_block.rb
index 3eb47fe82f67e129fe871b2085ae68fdca99d806..053294e7ffda6ff76f15e64c39f324b2aa636b10 100644
--- a/Library/Homebrew/cask/artifact/abstract_flight_block.rb
+++ b/Library/Homebrew/cask/artifact/abstract_flight_block.rb
@@ -4,6 +4,9 @@ require "cask/artifact/abstract_artifact"
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 272404635ca440bf0337856f5e6d97923e549a5f..e6d17348d505153c09747f47dc076aea5ba17df2 100644
--- a/Library/Homebrew/cask/artifact/abstract_uninstall.rb
+++ b/Library/Homebrew/cask/artifact/abstract_uninstall.rb
@@ -10,6 +10,9 @@ using HashValidator
module Cask
module Artifact
+ # Abstract superclass for uninstall artifacts.
+ #
+ # @api private
class AbstractUninstall < AbstractArtifact
ORDERED_DIRECTIVES = [
:early_script,
diff --git a/Library/Homebrew/cask/artifact/app.rb b/Library/Homebrew/cask/artifact/app.rb
index 99bf5fcbb525437937fbe1c1d3078618d00591aa..01cbec77f474f62c30417db2bfd7df6058ea8f01 100644
--- a/Library/Homebrew/cask/artifact/app.rb
+++ b/Library/Homebrew/cask/artifact/app.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
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 1252f40f034055126a5754630e9a5e9160c0e7d9..3d81ab65b0cf99eddf9f69da9b111dda249bfe02 100644
--- a/Library/Homebrew/cask/artifact/artifact.rb
+++ b/Library/Homebrew/cask/artifact/artifact.rb
@@ -7,6 +7,9 @@ using HashValidator
module Cask
module Artifact
+ # Generic artifact corresponding to the `artifact` stanza.
+ #
+ # @api private
class Artifact < Moved
def self.english_name
"Generic Artifact"
diff --git a/Library/Homebrew/cask/artifact/audio_unit_plugin.rb b/Library/Homebrew/cask/artifact/audio_unit_plugin.rb
index b027d294d3c5d9599b69eccac16ae5b071bd9d5f..c22c132d46e896a66ac009125fadb9113e37d5ca 100644
--- a/Library/Homebrew/cask/artifact/audio_unit_plugin.rb
+++ b/Library/Homebrew/cask/artifact/audio_unit_plugin.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
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 39c525762e15d13b3f3e9b15504ce905e84a3e74..a1f817ca7e93e3aaf8a0dc60478cd4f6da44f54c 100644
--- a/Library/Homebrew/cask/artifact/binary.rb
+++ b/Library/Homebrew/cask/artifact/binary.rb
@@ -4,6 +4,9 @@ require "cask/artifact/symlinked"
module Cask
module Artifact
+ # Artifact corresponding to the `binary` stanza.
+ #
+ # @api private
class Binary < Symlinked
def link(command: nil, **options)
super(command: command, **options)
diff --git a/Library/Homebrew/cask/artifact/colorpicker.rb b/Library/Homebrew/cask/artifact/colorpicker.rb
index 627260c333b501ecec3725111c3f737db4d76cda..48b2452455dc67ff0be6be7e223287ca5ea799f7 100644
--- a/Library/Homebrew/cask/artifact/colorpicker.rb
+++ b/Library/Homebrew/cask/artifact/colorpicker.rb
@@ -3,6 +3,9 @@
require "cask/artifact/moved"
module Cask
+ # Artifact corresponding to the `colorpicker` stanza.
+ #
+ # @api private
module Artifact
class Colorpicker < Moved
end
diff --git a/Library/Homebrew/cask/artifact/dictionary.rb b/Library/Homebrew/cask/artifact/dictionary.rb
index fe2c2b65b141b108206bed1704ff39e6da542561..03fded17ff368ef1b7cc0bad78fcfb20c48058d7 100644
--- a/Library/Homebrew/cask/artifact/dictionary.rb
+++ b/Library/Homebrew/cask/artifact/dictionary.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
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 3f9f38518939499e4c25d27d37e29b81dc2670e0..164731c166145e7ef62cb7cbce1d61dfe8ae8d06 100644
--- a/Library/Homebrew/cask/artifact/font.rb
+++ b/Library/Homebrew/cask/artifact/font.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
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 80249518443ef43d9a4e0341ac9926ac790227c9..9cd6b362394241a629c9e945526a59897e39634f 100644
--- a/Library/Homebrew/cask/artifact/input_method.rb
+++ b/Library/Homebrew/cask/artifact/input_method.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
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 e1be5f5054cd0a2c7f99eea3ff228e0986abf5d6..7ec14f611e1be17010c239ca99772260159ac790 100644
--- a/Library/Homebrew/cask/artifact/installer.rb
+++ b/Library/Homebrew/cask/artifact/installer.rb
@@ -7,12 +7,16 @@ using HashValidator
module Cask
module Artifact
+ # Artifact corresponding to the `installer` stanza.
+ #
+ # @api private
class Installer < AbstractArtifact
VALID_KEYS = Set.new([
:manual,
:script,
]).freeze
+ # Extension module for manual installers.
module ManualInstaller
def install_phase(**)
puts <<~EOS
@@ -23,6 +27,7 @@ module Cask
end
end
+ # Extension module for script installers.
module ScriptInstaller
def install_phase(command: nil, **_)
ohai "Running #{self.class.dsl_key} script '#{path}'"
diff --git a/Library/Homebrew/cask/artifact/internet_plugin.rb b/Library/Homebrew/cask/artifact/internet_plugin.rb
index 21dd0b37f10af0e5dad6b18638cbaee45bbb27d4..6e22874a463339eb636ba92547a9483bfd1e381f 100644
--- a/Library/Homebrew/cask/artifact/internet_plugin.rb
+++ b/Library/Homebrew/cask/artifact/internet_plugin.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
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/manpage.rb b/Library/Homebrew/cask/artifact/manpage.rb
index 942a83c43846d95cceef5df1400e9eb500a8364e..66453f2dba695dce9f69aebab6cb69614102a780 100644
--- a/Library/Homebrew/cask/artifact/manpage.rb
+++ b/Library/Homebrew/cask/artifact/manpage.rb
@@ -4,6 +4,9 @@ require "cask/artifact/symlinked"
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 ab4a3527bf0a606cf4a475ea5cc2cb5a97377150..c11cb9cc4b2ee10ce8c385eebd2ec67c65c33b84 100644
--- a/Library/Homebrew/cask/artifact/mdimporter.rb
+++ b/Library/Homebrew/cask/artifact/mdimporter.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
module Cask
module Artifact
+ # Artifact corresponding to the `mdimporter` stanza.
+ #
+ # @api private
class Mdimporter < Moved
def self.english_name
"Spotlight metadata importer"
diff --git a/Library/Homebrew/cask/artifact/moved.rb b/Library/Homebrew/cask/artifact/moved.rb
index 7774bff8ec110d9a45d67e9ba9409eb500758955..5925b86f4b5e24f4a62a9784a22d463bb8fcccb1 100644
--- a/Library/Homebrew/cask/artifact/moved.rb
+++ b/Library/Homebrew/cask/artifact/moved.rb
@@ -4,6 +4,9 @@ require "cask/artifact/relocated"
module Cask
module Artifact
+ # Superclass for all artifacts which are installed by moving them to the target location.
+ #
+ # @api private
class Moved < Relocated
def self.english_description
"#{english_name}s"
diff --git a/Library/Homebrew/cask/artifact/pkg.rb b/Library/Homebrew/cask/artifact/pkg.rb
index 075de456e19e5ca518348f2641a242fcfc0b584a..c70f2658dc401bb97c76189226c41a9af22bf104 100644
--- a/Library/Homebrew/cask/artifact/pkg.rb
+++ b/Library/Homebrew/cask/artifact/pkg.rb
@@ -10,6 +10,9 @@ using HashValidator
module Cask
module Artifact
+ # Artifact corresponding to the `pkg` stanza.
+ #
+ # @api private
class Pkg < AbstractArtifact
attr_reader :pkg_relative_path, :path, :stanza_options
diff --git a/Library/Homebrew/cask/artifact/postflight_block.rb b/Library/Homebrew/cask/artifact/postflight_block.rb
index 43cb49f5bd13ff03533530f7483bece121a1be6c..c672057d8c1102b5b3f6bf74fcbb78e027507957 100644
--- a/Library/Homebrew/cask/artifact/postflight_block.rb
+++ b/Library/Homebrew/cask/artifact/postflight_block.rb
@@ -4,6 +4,9 @@ require "cask/artifact/abstract_flight_block"
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 341cdb1e0f907da2fee3ce8c04c20c9e9c9dca39..f6f8882c71ca62bb41fc88fd2019de625d451e53 100644
--- a/Library/Homebrew/cask/artifact/preflight_block.rb
+++ b/Library/Homebrew/cask/artifact/preflight_block.rb
@@ -4,6 +4,9 @@ require "cask/artifact/abstract_flight_block"
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 393d6e5c4aacc95e462d95cfb18462e88f562ed3..8447c67c1d4abbed326ef64cbe1e011677ba8e56 100644
--- a/Library/Homebrew/cask/artifact/prefpane.rb
+++ b/Library/Homebrew/cask/artifact/prefpane.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
module Cask
module Artifact
+ # Artifact corresponding to the `prefpane` stanza.
+ #
+ # @api private
class Prefpane < Moved
def self.english_name
"Preference Pane"
diff --git a/Library/Homebrew/cask/artifact/qlplugin.rb b/Library/Homebrew/cask/artifact/qlplugin.rb
index b9c5f8f069ab6c50a7a4a9ffa9358dc79186950a..30588c6236db7f10e5107fdb2b7be89693a4c1a0 100644
--- a/Library/Homebrew/cask/artifact/qlplugin.rb
+++ b/Library/Homebrew/cask/artifact/qlplugin.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
module Cask
module Artifact
+ # Artifact corresponding to the `qlplugin` stanza.
+ #
+ # @api private
class Qlplugin < Moved
def self.english_name
"QuickLook Plugin"
diff --git a/Library/Homebrew/cask/artifact/relocated.rb b/Library/Homebrew/cask/artifact/relocated.rb
index 81e47f73c9406a7db97155d27af8e297b9ecfbf0..3f0da05eb0ddeaa6fae63a3ba1d277b345d8aa0c 100644
--- a/Library/Homebrew/cask/artifact/relocated.rb
+++ b/Library/Homebrew/cask/artifact/relocated.rb
@@ -7,6 +7,9 @@ using HashValidator
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 ba304162567fddcb182ec76615499e627aac52bc..f8f73e70212feffcaa2c972100d9724c108c4938 100644
--- a/Library/Homebrew/cask/artifact/screen_saver.rb
+++ b/Library/Homebrew/cask/artifact/screen_saver.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
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 b42d22c43edc2747f60bb3638cf235265cb55abc..9a92a6506f772a15485a9a8acba445e3506817f4 100644
--- a/Library/Homebrew/cask/artifact/service.rb
+++ b/Library/Homebrew/cask/artifact/service.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
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 77ae2270751bb1dd4c29d9f70f47e39c4badf762..78efa24d5d6d8f76cd8005e28d83fa052abdc7fd 100644
--- a/Library/Homebrew/cask/artifact/stage_only.rb
+++ b/Library/Homebrew/cask/artifact/stage_only.rb
@@ -4,6 +4,9 @@ require "cask/artifact/abstract_artifact"
module Cask
module Artifact
+ # Artifact corresponding to the `stage_only` stanza.
+ #
+ # @api private
class StageOnly < AbstractArtifact
def self.from_args(cask, *args)
raise CaskInvalidError.new(cask.token, "'stage_only' takes only a single argument: true") if args != [true]
diff --git a/Library/Homebrew/cask/artifact/suite.rb b/Library/Homebrew/cask/artifact/suite.rb
index 4d8332f70949e6f242d57ed06d014b9e23abd6f7..be8f348205aad87c01c6f13e7f4ec18df66b0d44 100644
--- a/Library/Homebrew/cask/artifact/suite.rb
+++ b/Library/Homebrew/cask/artifact/suite.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
module Cask
module Artifact
+ # Artifact corresponding to the `suite` stanza.
+ #
+ # @api private
class Suite < Moved
def self.english_name
"App Suite"
diff --git a/Library/Homebrew/cask/artifact/symlinked.rb b/Library/Homebrew/cask/artifact/symlinked.rb
index b50c104dc44f36243e927eee2e8ef83a9b53f971..fd40619fadfc77ebce14b96c2cca5b8ae289b191 100644
--- a/Library/Homebrew/cask/artifact/symlinked.rb
+++ b/Library/Homebrew/cask/artifact/symlinked.rb
@@ -4,6 +4,9 @@ require "cask/artifact/relocated"
module Cask
module Artifact
+ # Superclass for all artifacts which are installed by symlinking them to the target location.
+ #
+ # @api private
class Symlinked < Relocated
def self.link_type_english_name
"Symlink"
diff --git a/Library/Homebrew/cask/artifact/uninstall.rb b/Library/Homebrew/cask/artifact/uninstall.rb
index cdd2da2b8636dc120349543e92777476cbfb98cc..00b385e64727e4282d1ba5ec360d1d9423e6ea5c 100644
--- a/Library/Homebrew/cask/artifact/uninstall.rb
+++ b/Library/Homebrew/cask/artifact/uninstall.rb
@@ -4,6 +4,9 @@ require "cask/artifact/abstract_uninstall"
module Cask
module Artifact
+ # Artifact corresponding to the `uninstall` stanza.
+ #
+ # @api private
class Uninstall < AbstractUninstall
def uninstall_phase(**options)
ORDERED_DIRECTIVES.reject { |directive_sym| directive_sym == :rmdir }
diff --git a/Library/Homebrew/cask/artifact/vst3_plugin.rb b/Library/Homebrew/cask/artifact/vst3_plugin.rb
index ea5dc05d058d07fff062a32601ea4ac5fae27f92..e82690d84bc723bf5977dcbc0598d55add5bc0ff 100644
--- a/Library/Homebrew/cask/artifact/vst3_plugin.rb
+++ b/Library/Homebrew/cask/artifact/vst3_plugin.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
module Cask
module Artifact
+ # Artifact corresponding to the `vst3_plugin` stanza.
+ #
+ # @api private
class Vst3Plugin < Moved
end
end
diff --git a/Library/Homebrew/cask/artifact/vst_plugin.rb b/Library/Homebrew/cask/artifact/vst_plugin.rb
index 6796e286ca7c7c99e0605b62a3a1714ddad4df20..058ea5052139bc2df3e50c54ce5dacc55ad2e647 100644
--- a/Library/Homebrew/cask/artifact/vst_plugin.rb
+++ b/Library/Homebrew/cask/artifact/vst_plugin.rb
@@ -4,6 +4,9 @@ require "cask/artifact/moved"
module Cask
module Artifact
+ # Artifact corresponding to the `vst_plugin` stanza.
+ #
+ # @api private
class VstPlugin < Moved
end
end
diff --git a/Library/Homebrew/cask/artifact/zap.rb b/Library/Homebrew/cask/artifact/zap.rb
index cd1ccc736da81436a984ac3d8eb1e586fe004d7e..6967f922c7e6b86a921f9fa2c3e5edd606f18658 100644
--- a/Library/Homebrew/cask/artifact/zap.rb
+++ b/Library/Homebrew/cask/artifact/zap.rb
@@ -4,6 +4,9 @@ require "cask/artifact/abstract_uninstall"
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/audit.rb b/Library/Homebrew/cask/audit.rb
index f5cd9c2315e8274e580832ddf7700d1ef707407c..70f5d364cc91452093bc24b45e2f0a5b3ab7398e 100644
--- a/Library/Homebrew/cask/audit.rb
+++ b/Library/Homebrew/cask/audit.rb
@@ -8,6 +8,9 @@ require "utils/git"
require "utils/notability"
module Cask
+ # Audit a cask for various problems.
+ #
+ # @api private
class Audit
extend Predicable
diff --git a/Library/Homebrew/cask/auditor.rb b/Library/Homebrew/cask/auditor.rb
index cc31909c8f3d09e928af16f36039f633c9c52db3..9aa4820a560e7f93a4db31e824f4aae111551b9f 100644
--- a/Library/Homebrew/cask/auditor.rb
+++ b/Library/Homebrew/cask/auditor.rb
@@ -3,6 +3,9 @@
require "cask/audit"
module Cask
+ # Helper class for auditing all available languages of a cask.
+ #
+ # @api private
class Auditor
extend Predicable
diff --git a/Library/Homebrew/cask/cache.rb b/Library/Homebrew/cask/cache.rb
index 2286398620650983559aeb92e529d6905584594d..2d1dcc570627778b54b9565a23667c8972d4318f 100644
--- a/Library/Homebrew/cask/cache.rb
+++ b/Library/Homebrew/cask/cache.rb
@@ -1,6 +1,9 @@
# frozen_string_literal: true
module Cask
+ # Helper functions for the cask cache.
+ #
+ # @api private
module Cache
module_function
diff --git a/Library/Homebrew/cask/cask.rb b/Library/Homebrew/cask/cask.rb
index 93301a09588f9d76af611fd55086949d19ccbfcc..c04105c18a269cbf20dcdff7597537235314fd64 100644
--- a/Library/Homebrew/cask/cask.rb
+++ b/Library/Homebrew/cask/cask.rb
@@ -7,6 +7,9 @@ require "cask/metadata"
require "searchable"
module Cask
+ # An instance of a cask.
+ #
+ # @api private
class Cask
extend Enumerable
extend Forwardable
diff --git a/Library/Homebrew/cask/cask_loader.rb b/Library/Homebrew/cask/cask_loader.rb
index 3ffd79761b451552e65222e6eb7cab8d26e626f2..0917bbbd3a8642e228910f1d9fe042725d349002 100644
--- a/Library/Homebrew/cask/cask_loader.rb
+++ b/Library/Homebrew/cask/cask_loader.rb
@@ -4,7 +4,11 @@ require "cask/cask"
require "uri"
module Cask
+ # Loads a cask from various sources.
+ #
+ # @api private
module CaskLoader
+ # Loads a cask from a string.
class FromContentLoader
attr_reader :content
@@ -36,6 +40,7 @@ module Cask
end
end
+ # Loads a cask from a path.
class FromPathLoader < FromContentLoader
def self.can_load?(ref)
path = Pathname(ref)
@@ -76,6 +81,7 @@ module Cask
end
end
+ # Loads a cask from a URI.
class FromURILoader < FromPathLoader
def self.can_load?(ref)
uri_regex = ::URI::DEFAULT_PARSER.make_regexp
@@ -109,6 +115,7 @@ module Cask
end
end
+ # Loads a cask from a tap path.
class FromTapPathLoader < FromPathLoader
def self.can_load?(ref)
super && !Tap.from_path(ref).nil?
@@ -128,6 +135,7 @@ module Cask
end
end
+ # Loads a cask from a specific tap.
class FromTapLoader < FromTapPathLoader
def self.can_load?(ref)
ref.to_s.match?(HOMEBREW_TAP_CASK_REGEX)
@@ -145,6 +153,7 @@ module Cask
end
end
+ # Loads a cask from an existing {Cask} instance.
class FromInstanceLoader
attr_reader :cask
@@ -161,6 +170,7 @@ module Cask
end
end
+ # Pseudo-loader which raises an error when trying to load the corresponding cask.
class NullLoader < FromPathLoader
def self.can_load?(*)
true
diff --git a/Library/Homebrew/cask/caskroom.rb b/Library/Homebrew/cask/caskroom.rb
index 542ea0bcadff3fae1e18663c3b4e45dbbacd5aba..e3519440bbc3b7651f71c40cfdcf2dcfa99e2692 100644
--- a/Library/Homebrew/cask/caskroom.rb
+++ b/Library/Homebrew/cask/caskroom.rb
@@ -3,6 +3,9 @@
require "utils/user"
module Cask
+ # Helper functions for interacting with the `Caskroom` directory.
+ #
+ # @api private
module Caskroom
module_function
diff --git a/Library/Homebrew/cask/cmd.rb b/Library/Homebrew/cask/cmd.rb
index 674f4f452edf362ccb7bf13b1d4dd30a0baa6830..b353a79fc67f94edfffbdf105b2c08937ba56008 100644
--- a/Library/Homebrew/cask/cmd.rb
+++ b/Library/Homebrew/cask/cmd.rb
@@ -33,6 +33,9 @@ require "cask/cmd/internal_help"
require "cask/cmd/internal_stanza"
module Cask
+ # Implementation of the `brew cask` command-line interface.
+ #
+ # @api private
class Cmd
include Context
@@ -240,6 +243,7 @@ module Cask
exit 1
end
+ # Wrapper class for running an external Ruby command.
class ExternalRubyCommand
def initialize(command, path)
@command_name = command.to_s.capitalize.to_sym
@@ -269,6 +273,7 @@ module Cask
end
end
+ # Wrapper class for running an external command.
class ExternalCommand
def initialize(path)
@path = path
@@ -283,6 +288,7 @@ module Cask
end
end
+ # Helper class for showing help for unknown subcommands.
class UnknownSubcommand
def initialize(command_name)
@command_name = command_name
@@ -297,6 +303,7 @@ module Cask
end
end
+ # Helper class for showing help when no subcommand is given.
class NullCommand
def self.run(*)
raise UsageError, "No subcommand given."
diff --git a/Library/Homebrew/cask/cmd/--cache.rb b/Library/Homebrew/cask/cmd/--cache.rb
index 310c79d84e9f4ccf0495759de48d76934a77b609..81d3acc7dee4efe3311b1e16d3f3d8fb848f57ae 100644
--- a/Library/Homebrew/cask/cmd/--cache.rb
+++ b/Library/Homebrew/cask/cmd/--cache.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask --cache` command.
+ #
+ # @api private
class Cache < AbstractCommand
def self.min_named
:cask
diff --git a/Library/Homebrew/cask/cmd/abstract_command.rb b/Library/Homebrew/cask/cmd/abstract_command.rb
index 2b768e69c21fd89a603e0ab5a4534ef24be56d54..c19cb187264719524cad261cee31e7b6ca43abfd 100644
--- a/Library/Homebrew/cask/cmd/abstract_command.rb
+++ b/Library/Homebrew/cask/cmd/abstract_command.rb
@@ -4,6 +4,9 @@ require "search"
module Cask
class Cmd
+ # Abstract superclass for all `brew cask` commands.
+ #
+ # @api private
class AbstractCommand
include Homebrew::Search
diff --git a/Library/Homebrew/cask/cmd/abstract_internal_command.rb b/Library/Homebrew/cask/cmd/abstract_internal_command.rb
index 61cfec4fe26495e17964881c975ef97d5af11d21..b15b9acc907cacc2bed4e06b4742d1b9d3fee61d 100644
--- a/Library/Homebrew/cask/cmd/abstract_internal_command.rb
+++ b/Library/Homebrew/cask/cmd/abstract_internal_command.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Abstract superclass for all internal `brew cask` commands.
+ #
+ # @api private
class AbstractInternalCommand < AbstractCommand
def self.command_name
super.sub(/^internal_/i, "_")
diff --git a/Library/Homebrew/cask/cmd/audit.rb b/Library/Homebrew/cask/cmd/audit.rb
index ee457e9f76a2a0e8ddf97d9a14b3fc1843a9534e..6bf08325a45a1d02b0156f5a19fbe6a69c84440b 100644
--- a/Library/Homebrew/cask/cmd/audit.rb
+++ b/Library/Homebrew/cask/cmd/audit.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask audit` command.
+ #
+ # @api private
class Audit < AbstractCommand
def self.description
<<~EOS
diff --git a/Library/Homebrew/cask/cmd/cat.rb b/Library/Homebrew/cask/cmd/cat.rb
index a75158ae305c6a6169836c7384b197c3b967ce3d..3d731b1d6c58faf28c5f28315d6db66a10ccbf45 100644
--- a/Library/Homebrew/cask/cmd/cat.rb
+++ b/Library/Homebrew/cask/cmd/cat.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask cat` command.
+ #
+ # @api private
class Cat < AbstractCommand
def self.min_named
:cask
diff --git a/Library/Homebrew/cask/cmd/create.rb b/Library/Homebrew/cask/cmd/create.rb
index 099b5fd737ae44e3bd3eb5341a56f08cb0f9c71c..c190161fa6f5785988a6a13744b30950f02dab31 100644
--- a/Library/Homebrew/cask/cmd/create.rb
+++ b/Library/Homebrew/cask/cmd/create.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask create` command.
+ #
+ # @api private
class Create < AbstractCommand
def self.min_named
:cask
diff --git a/Library/Homebrew/cask/cmd/doctor.rb b/Library/Homebrew/cask/cmd/doctor.rb
index c05248344551a1493c3e2c548c8f2a6071d52791..dafc4e57747ee44adedba891dcc9db1d7e1f6f3a 100644
--- a/Library/Homebrew/cask/cmd/doctor.rb
+++ b/Library/Homebrew/cask/cmd/doctor.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask doctor` command.
+ #
+ # @api private
class Doctor < AbstractCommand
def self.max_named
0
diff --git a/Library/Homebrew/cask/cmd/edit.rb b/Library/Homebrew/cask/cmd/edit.rb
index 94798b786f171e843d62d47ddb74842e6c15a04f..bbeffbf7308046eb78ac1e87cb5f03131a389840 100644
--- a/Library/Homebrew/cask/cmd/edit.rb
+++ b/Library/Homebrew/cask/cmd/edit.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask edit` command.
+ #
+ # @api private
class Edit < AbstractCommand
def self.min_named
:cask
diff --git a/Library/Homebrew/cask/cmd/fetch.rb b/Library/Homebrew/cask/cmd/fetch.rb
index 141ae73e765d0af6d08f907a23560bc6a92f6249..e42208a31b541e86df4ea95c9b320b624fb396c7 100644
--- a/Library/Homebrew/cask/cmd/fetch.rb
+++ b/Library/Homebrew/cask/cmd/fetch.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask fetch` command.
+ #
+ # @api private
class Fetch < AbstractCommand
def self.min_named
:cask
diff --git a/Library/Homebrew/cask/cmd/help.rb b/Library/Homebrew/cask/cmd/help.rb
index bef0e9b0ce15cf2c5081562bb048d787b72aa5cc..fee20683db701fef1885af0efdc1787342639d2f 100644
--- a/Library/Homebrew/cask/cmd/help.rb
+++ b/Library/Homebrew/cask/cmd/help.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask help` command.
+ #
+ # @api private
class Help < AbstractCommand
def self.max_named
1
diff --git a/Library/Homebrew/cask/cmd/home.rb b/Library/Homebrew/cask/cmd/home.rb
index 22a32486ec45c34899b0a57064275b88082f1028..291256519af3beb027a70ab9ccf6c149f7a67592 100644
--- a/Library/Homebrew/cask/cmd/home.rb
+++ b/Library/Homebrew/cask/cmd/home.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask home` command.
+ #
+ # @api private
class Home < AbstractCommand
def self.description
"Opens the homepage of the given <cask>. If no cask is given, opens the Homebrew homepage."
diff --git a/Library/Homebrew/cask/cmd/info.rb b/Library/Homebrew/cask/cmd/info.rb
index a52a40464b566057e0a427b0a81cd24ca19669bb..9667f2bfc21b77eca55b46ffa91b33d9d29515bb 100644
--- a/Library/Homebrew/cask/cmd/info.rb
+++ b/Library/Homebrew/cask/cmd/info.rb
@@ -4,6 +4,9 @@ require "json"
module Cask
class Cmd
+ # Implementation of the `brew cask info` command.
+ #
+ # @api private
class Info < AbstractCommand
def self.min_named
:cask
diff --git a/Library/Homebrew/cask/cmd/install.rb b/Library/Homebrew/cask/cmd/install.rb
index 55b8f77ee8bc8a9c92ed5fd19d8444e8dd1f8cb3..93d03d1fb270a8612a068438489e10f717c48733 100644
--- a/Library/Homebrew/cask/cmd/install.rb
+++ b/Library/Homebrew/cask/cmd/install.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask install` command.
+ #
+ # @api private
class Install < AbstractCommand
def self.min_named
:cask
diff --git a/Library/Homebrew/cask/cmd/internal_help.rb b/Library/Homebrew/cask/cmd/internal_help.rb
index 878a07bad8c8939f380ae853a7836d282ab31352..edd33fc2dfbf2790bd365d0dff32df6734e46e43 100644
--- a/Library/Homebrew/cask/cmd/internal_help.rb
+++ b/Library/Homebrew/cask/cmd/internal_help.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask _help` command.
+ #
+ # @api private
class InternalHelp < AbstractInternalCommand
def self.max_named
0
diff --git a/Library/Homebrew/cask/cmd/internal_stanza.rb b/Library/Homebrew/cask/cmd/internal_stanza.rb
index 41f91ebf5c4f6f4545417f6f4d9e45beae72eab7..c392d508a37917bd78a30f5cc581ec93d865f70c 100644
--- a/Library/Homebrew/cask/cmd/internal_stanza.rb
+++ b/Library/Homebrew/cask/cmd/internal_stanza.rb
@@ -4,6 +4,9 @@ require "cask/dsl"
module Cask
class Cmd
+ # Implementation of the `brew cask _stanza` command.
+ #
+ # @api private
class InternalStanza < AbstractInternalCommand
# Syntax
#
diff --git a/Library/Homebrew/cask/cmd/list.rb b/Library/Homebrew/cask/cmd/list.rb
index 87098cf91755f3668be4dec17281d153893225a2..55f6e937cd6ba1cba2bc63bc3b365e03a0c5b032 100644
--- a/Library/Homebrew/cask/cmd/list.rb
+++ b/Library/Homebrew/cask/cmd/list.rb
@@ -4,6 +4,9 @@ require "cask/artifact/relocated"
module Cask
class Cmd
+ # Implementation of the `brew cask list` command.
+ #
+ # @api private
class List < AbstractCommand
def self.description
"Lists installed casks or the casks provided in the arguments."
diff --git a/Library/Homebrew/cask/cmd/outdated.rb b/Library/Homebrew/cask/cmd/outdated.rb
index 43675d5a101144797cbcc0bcca314b89dedb5788..c84a1358a4cdc25960ae0de9f52d67ea33d50b38 100644
--- a/Library/Homebrew/cask/cmd/outdated.rb
+++ b/Library/Homebrew/cask/cmd/outdated.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask outdated` command.
+ #
+ # @api private
class Outdated < AbstractCommand
def self.description
"List the outdated installed casks."
diff --git a/Library/Homebrew/cask/cmd/reinstall.rb b/Library/Homebrew/cask/cmd/reinstall.rb
index 2264b246be7638cd10b91607ee4d9c36c51fce13..6303a103535293ccba3033b87accdb9329d157e2 100644
--- a/Library/Homebrew/cask/cmd/reinstall.rb
+++ b/Library/Homebrew/cask/cmd/reinstall.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask reinstall` command.
+ #
+ # @api private
class Reinstall < Install
def self.description
"Reinstalls the given <cask>."
diff --git a/Library/Homebrew/cask/cmd/style.rb b/Library/Homebrew/cask/cmd/style.rb
index b24b1b5c204fad3120784e25af3335aff90ffb92..7db1ac6b57be1738fd73829261aa040ac1035ea8 100644
--- a/Library/Homebrew/cask/cmd/style.rb
+++ b/Library/Homebrew/cask/cmd/style.rb
@@ -4,6 +4,9 @@ require "json"
module Cask
class Cmd
+ # Implementation of the `brew cask style` command.
+ #
+ # @api private
class Style < AbstractCommand
def self.description
"Checks style of the given <cask> using RuboCop."
diff --git a/Library/Homebrew/cask/cmd/uninstall.rb b/Library/Homebrew/cask/cmd/uninstall.rb
index affb7cc7235444f51159c9436985b38fae8648e3..c02d68cf63d7ae9241d76aca5dbd3c6304c94613 100644
--- a/Library/Homebrew/cask/cmd/uninstall.rb
+++ b/Library/Homebrew/cask/cmd/uninstall.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask uninstall` command.
+ #
+ # @api private
class Uninstall < AbstractCommand
def self.min_named
:cask
diff --git a/Library/Homebrew/cask/cmd/upgrade.rb b/Library/Homebrew/cask/cmd/upgrade.rb
index 2562cdfab0a7100394fd3b69ec0ac370d037e6bb..7f56f805c0d1c3aed4a8f9fd5c4d7d652bbfb8ea 100644
--- a/Library/Homebrew/cask/cmd/upgrade.rb
+++ b/Library/Homebrew/cask/cmd/upgrade.rb
@@ -5,6 +5,9 @@ require "cask/config"
module Cask
class Cmd
+ # Implementation of the `brew cask upgrade` command.
+ #
+ # @api private
class Upgrade < AbstractCommand
def self.description
"Upgrades all outdated casks or the specified casks."
diff --git a/Library/Homebrew/cask/cmd/zap.rb b/Library/Homebrew/cask/cmd/zap.rb
index 2168588e776b034138a244a5588461bdcaecbf04..9b208899abb121dd6c441e4acc1a436136176d5b 100644
--- a/Library/Homebrew/cask/cmd/zap.rb
+++ b/Library/Homebrew/cask/cmd/zap.rb
@@ -2,6 +2,9 @@
module Cask
class Cmd
+ # Implementation of the `brew cask zap` command.
+ #
+ # @api private
class Zap < AbstractCommand
def self.min_named
:cask
diff --git a/Library/Homebrew/cask/config.rb b/Library/Homebrew/cask/config.rb
index ebfe171701d2caaaeae0ed9b17ebcd18014b45e8..2583478cce985eede3410a353e785181ce65881f 100644
--- a/Library/Homebrew/cask/config.rb
+++ b/Library/Homebrew/cask/config.rb
@@ -9,6 +9,9 @@ require "extend/hash_validator"
using HashValidator
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 86bd1151ae60e4f7cca21580314d3fae21e9e2ad..dda4326ba6a7a36b758fa07b4f72d0a1f503fb66 100644
--- a/Library/Homebrew/cask/denylist.rb
+++ b/Library/Homebrew/cask/denylist.rb
@@ -1,6 +1,9 @@
# frozen_string_literal: true
module Cask
+ # List of casks which are not allowed in official taps.
+ #
+ # @api private
module Denylist
def self.reason(name)
case name
diff --git a/Library/Homebrew/cask/download.rb b/Library/Homebrew/cask/download.rb
index 4bd4e4426a77d5963dcd60a7c2824e77c71ca632..16c1dbd81c123268b21e666f4f1b85208bd5f6da 100644
--- a/Library/Homebrew/cask/download.rb
+++ b/Library/Homebrew/cask/download.rb
@@ -6,6 +6,9 @@ require "cask/quarantine"
require "cask/verify"
module Cask
+ # A download corresponding to a {Cask}.
+ #
+ # @api private
class Download
attr_reader :cask
diff --git a/Library/Homebrew/cask/dsl.rb b/Library/Homebrew/cask/dsl.rb
index 98dd27a84301b86edf762f2ae23ceee358a9688d..cc8f451d98f5ea3792ea4038a63840e71aac3153 100644
--- a/Library/Homebrew/cask/dsl.rb
+++ b/Library/Homebrew/cask/dsl.rb
@@ -24,6 +24,9 @@ require "cask/url"
require "cask/utils"
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/appcast.rb b/Library/Homebrew/cask/dsl/appcast.rb
index 99821e6ddd5fe3c9fa4095f9c9393e74da137c5d..1c9ebc3600a51de01ede8925711a148a2c5a402e 100644
--- a/Library/Homebrew/cask/dsl/appcast.rb
+++ b/Library/Homebrew/cask/dsl/appcast.rb
@@ -2,6 +2,9 @@
module Cask
class DSL
+ # Class corresponding to the `appcast` stanza.
+ #
+ # @api private
class Appcast
attr_reader :uri, :parameters, :must_contain
diff --git a/Library/Homebrew/cask/dsl/base.rb b/Library/Homebrew/cask/dsl/base.rb
index bc9440de6fc7f4720e2c1a611f56d2e1fd09e227..4ea58e01e9499ba590c2b40f08b3931b5e320d4e 100644
--- a/Library/Homebrew/cask/dsl/base.rb
+++ b/Library/Homebrew/cask/dsl/base.rb
@@ -4,6 +4,9 @@ require "cask/utils"
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 b6105915e4eef03e9f0651ca147a019b000678b4..d9933d992c13bbd3babf749ef0928f565b6e6a62 100644
--- a/Library/Homebrew/cask/dsl/caveats.rb
+++ b/Library/Homebrew/cask/dsl/caveats.rb
@@ -1,14 +1,18 @@
# frozen_string_literal: true
-# Caveats DSL. Each method should handle output, following the
-# convention of at least one trailing blank line so that the user
-# can distinguish separate caveats.
-#
-# ( 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. )
module Cask
class DSL
+ # Class corresponding to the `caveats` stanza.
+ #
+ # Each method should handle output, following the
+ # convention of at least one trailing blank line so that the user
+ # can distinguish separate caveats.
+ #
+ # 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
def initialize(*args)
super(*args)
diff --git a/Library/Homebrew/cask/dsl/conflicts_with.rb b/Library/Homebrew/cask/dsl/conflicts_with.rb
index d90ecdb06e2edaed85bbb59c4c51fbd7dcf13d79..d5de4edeb96133434917de5a2fde54c75d655605 100644
--- a/Library/Homebrew/cask/dsl/conflicts_with.rb
+++ b/Library/Homebrew/cask/dsl/conflicts_with.rb
@@ -5,6 +5,9 @@ using HashValidator
module Cask
class DSL
+ # Class corresponding to the `conflicts_with` stanza.
+ #
+ # @api private
class ConflictsWith < DelegateClass(Hash)
VALID_KEYS = [
:formula,
diff --git a/Library/Homebrew/cask/dsl/container.rb b/Library/Homebrew/cask/dsl/container.rb
index 1d8a0dbc162ae25f52a589709f0b42a1feb1aff7..60cfbdb44e1a7e54eda20d97f36931cbd5acd74d 100644
--- a/Library/Homebrew/cask/dsl/container.rb
+++ b/Library/Homebrew/cask/dsl/container.rb
@@ -4,6 +4,9 @@ require "unpack_strategy"
module Cask
class DSL
+ # Class corresponding to the `container` stanza.
+ #
+ # @api private
class Container
VALID_KEYS = Set.new([
:type,
diff --git a/Library/Homebrew/cask/dsl/depends_on.rb b/Library/Homebrew/cask/dsl/depends_on.rb
index 257ff397838651d6df819375d86efce1d7e5f140..b8f701ab1180e3a15d64c60f6b7bec0df0d05a83 100644
--- a/Library/Homebrew/cask/dsl/depends_on.rb
+++ b/Library/Homebrew/cask/dsl/depends_on.rb
@@ -4,6 +4,9 @@ require "requirements/macos_requirement"
module Cask
class DSL
+ # Class corresponding to the `depends_on` stanza.
+ #
+ # @api private
class DependsOn < DelegateClass(Hash)
VALID_KEYS = Set.new([
:formula,
diff --git a/Library/Homebrew/cask/dsl/postflight.rb b/Library/Homebrew/cask/dsl/postflight.rb
index 9e0b1f55b69bd6f2b05b0892ed435282581dd7b5..cccfac6c9ed07889050ede5db00a32b957a54b23 100644
--- a/Library/Homebrew/cask/dsl/postflight.rb
+++ b/Library/Homebrew/cask/dsl/postflight.rb
@@ -4,6 +4,9 @@ require "cask/staged"
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 1cf1e03b56b97060a1a921cb9f6549b602480567..eba210668d8b1b6188fb67ddf523baa3be2f6398 100644
--- a/Library/Homebrew/cask/dsl/preflight.rb
+++ b/Library/Homebrew/cask/dsl/preflight.rb
@@ -2,6 +2,9 @@
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 db83749a22b2b8974e180636aba3f1fa52d01d71..fac89d764e23493a6b768509d635e4f349a128b4 100644
--- a/Library/Homebrew/cask/dsl/uninstall_postflight.rb
+++ b/Library/Homebrew/cask/dsl/uninstall_postflight.rb
@@ -2,6 +2,9 @@
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 25d8f1d0d5b2d68cdad4c3ba0db13d7599de3d03..770fc680a3d843198f74f79b8f289bab2877d3ec 100644
--- a/Library/Homebrew/cask/dsl/uninstall_preflight.rb
+++ b/Library/Homebrew/cask/dsl/uninstall_preflight.rb
@@ -4,6 +4,9 @@ require "cask/staged"
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 fd8328ad06115996526b9ff818b82dd081b6aefb..53d58b996121b6e292da92b1846f1c54ad86c8f4 100644
--- a/Library/Homebrew/cask/dsl/version.rb
+++ b/Library/Homebrew/cask/dsl/version.rb
@@ -2,6 +2,9 @@
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 9614b6780e51065653dbba4e1ad1b09af990ebb9..7a97f7f1333f482db46870e22142a717d5adc81e 100644
--- a/Library/Homebrew/cask/exceptions.rb
+++ b/Library/Homebrew/cask/exceptions.rb
@@ -1,8 +1,14 @@
# frozen_string_literal: true
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()
@@ -18,6 +24,9 @@ module Cask
end
end
+ # Abstract cask error containing a cask token.
+ #
+ # @api private
class AbstractCaskErrorWithToken < CaskError
attr_reader :token, :reason
@@ -29,12 +38,18 @@ module Cask
end
end
+ # Error when a cask is not installed.
+ #
+ # @api private
class CaskNotInstalledError < AbstractCaskErrorWithToken
def to_s
"Cask '#{token}' is not installed."
end
end
+ # Error when a cask conflicts with another cask.
+ #
+ # @api private
class CaskConflictError < AbstractCaskErrorWithToken
attr_reader :conflicting_cask
@@ -48,24 +63,36 @@ module Cask
end
end
+ # Error when a cask is not available.
+ #
+ # @api private
class CaskUnavailableError < AbstractCaskErrorWithToken
def to_s
"Cask '#{token}' is unavailable#{reason.empty? ? "." : ": #{reason}"}"
end
end
+ # Error when a cask is unreadable.
+ #
+ # @api private
class CaskUnreadableError < CaskUnavailableError
def to_s
"Cask '#{token}' is unreadable#{reason.empty? ? "." : ": #{reason}"}"
end
end
+ # Error when a cask already exists.
+ #
+ # @api private
class CaskAlreadyCreatedError < AbstractCaskErrorWithToken
def to_s
%Q(Cask '#{token}' already exists. Run #{Formatter.identifier("brew cask edit #{token}")} to edit it.)
end
end
+ # Error when a cask is already installed.
+ #
+ # @api private
class CaskAlreadyInstalledError < AbstractCaskErrorWithToken
def to_s
<<~EOS
@@ -77,6 +104,9 @@ module Cask
end
end
+ # Error when a cask depends on X11.
+ #
+ # @api private
class CaskX11DependencyError < AbstractCaskErrorWithToken
def to_s
<<~EOS
@@ -89,36 +119,54 @@ module Cask
end
end
+ # Error when there is a cyclic cask dependency.
+ #
+ # @api private
class CaskCyclicDependencyError < AbstractCaskErrorWithToken
def to_s
"Cask '#{token}' includes cyclic dependencies on other Casks#{reason.empty? ? "." : ": #{reason}"}"
end
end
+ # Error when a cask depends on itself.
+ #
+ # @api private
class CaskSelfReferencingDependencyError < CaskCyclicDependencyError
def to_s
"Cask '#{token}' depends on itself."
end
end
+ # Error when no cask is specified.
+ #
+ # @api private
class CaskUnspecifiedError < CaskError
def to_s
"This command requires a Cask token."
end
end
+ # Error when a cask is invalid.
+ #
+ # @api private
class CaskInvalidError < AbstractCaskErrorWithToken
def to_s
"Cask '#{token}' definition is invalid#{reason.empty? ? "." : ": #{reason}"}"
end
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.")
end
end
+ # Error with a cask's checksum.
+ #
+ # @api private
class CaskSha256Error < AbstractCaskErrorWithToken
attr_reader :expected, :actual
@@ -129,6 +177,9 @@ module Cask
end
end
+ # Error when a cask's checksum is missing.
+ #
+ # @api private
class CaskSha256MissingError < CaskSha256Error
def to_s
<<~EOS
@@ -138,6 +189,9 @@ module Cask
end
end
+ # Error when a cask's checksum does not match.
+ #
+ # @api private
class CaskSha256MismatchError < CaskSha256Error
attr_reader :path
@@ -159,6 +213,9 @@ module Cask
end
end
+ # Error when a cask has no checksum and the `--require-sha` flag is passed.
+ #
+ # @api private
class CaskNoShasumError < CaskSha256Error
def to_s
<<~EOS
@@ -168,6 +225,9 @@ module Cask
end
end
+ # Error during quarantining of a file.
+ #
+ # @api private
class CaskQuarantineError < CaskError
attr_reader :path, :reason
@@ -191,6 +251,9 @@ module Cask
end
end
+ # Error while propagating quarantine information to subdirectories.
+ #
+ # @api private
class CaskQuarantinePropagationError < CaskQuarantineError
def to_s
s = +"Failed to quarantine one or more files within #{path}."
@@ -205,6 +268,9 @@ module Cask
end
end
+ # Error while removing quarantine information.
+ #
+ # @api private
class CaskQuarantineReleaseError < CaskQuarantineError
def to_s
s = +"Failed to release #{path} from quarantine."
diff --git a/Library/Homebrew/cask/installer.rb b/Library/Homebrew/cask/installer.rb
index 5ad75d01cef7a04219b1cd8f5ae6b4d7a833bb91..e28e4fa0936f7e41de4e698f069ade01a6d13e5e 100644
--- a/Library/Homebrew/cask/installer.rb
+++ b/Library/Homebrew/cask/installer.rb
@@ -13,6 +13,9 @@ require "cask/quarantine"
require "cgi"
module Cask
+ # Installer for a {Cask}.
+ #
+ # @api private
class Installer
extend Predicable
# TODO: it is unwise for Cask::Staged to be a module, when we are
diff --git a/Library/Homebrew/cask/macos.rb b/Library/Homebrew/cask/macos.rb
index 49e34caed87f4240e18c04386fb46e49b4c89efd..cf65def619934223fa6eadc4215047e984e81ca4 100644
--- a/Library/Homebrew/cask/macos.rb
+++ b/Library/Homebrew/cask/macos.rb
@@ -238,6 +238,7 @@ module OS
.map(&method(:Pathname))
.to_set
.freeze
+ private_constant :SYSTEM_DIRS
# TODO: There should be a way to specify a containing
# directory under which nothing can be deleted.
@@ -380,6 +381,7 @@ module OS
.to_set
.union(SYSTEM_DIRS)
.freeze
+ private_constant :UNDELETABLE_PATHS
def system_dir?(dir)
SYSTEM_DIRS.include?(Pathname.new(dir).expand_path)
diff --git a/Library/Homebrew/cask/metadata.rb b/Library/Homebrew/cask/metadata.rb
index b15fbdda394aa418549b4fc917e6d4cd99471340..8c12de10bb42e9201fdf5301820035e76130fdf4 100644
--- a/Library/Homebrew/cask/metadata.rb
+++ b/Library/Homebrew/cask/metadata.rb
@@ -1,6 +1,9 @@
# frozen_string_literal: true
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 f6c4a2444fa948a81ceec40fb24df27dc523577c..f015ee9de80ff736fef4a499247bbdd8dbab4106 100644
--- a/Library/Homebrew/cask/pkg.rb
+++ b/Library/Homebrew/cask/pkg.rb
@@ -3,6 +3,9 @@
require "cask/macos"
module Cask
+ # Helper class for uninstalling `.pkg` installers.
+ #
+ # @api private
class Pkg
def self.all_matching(regexp, command)
command.run("/usr/sbin/pkgutil", args: ["--pkgs=#{regexp}"]).stdout.split("\n").map do |package_id|
diff --git a/Library/Homebrew/cask/quarantine.rb b/Library/Homebrew/cask/quarantine.rb
index 381ee80a06240191c25d82ecfcbb2c0fb28ccaeb..a90a7ea942c8ea08ee62661bdf2d914ce3b1b515 100644
--- a/Library/Homebrew/cask/quarantine.rb
+++ b/Library/Homebrew/cask/quarantine.rb
@@ -4,6 +4,9 @@ require "development_tools"
require "cask/exceptions"
module Cask
+ # Helper module for quarantining files.
+ #
+ # @api private
module Quarantine
module_function
@@ -11,15 +14,15 @@ module Cask
QUARANTINE_SCRIPT = (HOMEBREW_LIBRARY_PATH/"cask/utils/quarantine.swift").freeze
- # @private
def swift
@swift ||= DevelopmentTools.locate("swift")
end
+ private :swift
- # @private
def xattr
@xattr ||= DevelopmentTools.locate("xattr")
end
+ private :xattr
def check_quarantine_support
odebug "Checking quarantine support"
diff --git a/Library/Homebrew/cask/staged.rb b/Library/Homebrew/cask/staged.rb
index b0216fc34427661bdc28d462c3131c4c585afd2d..73dd826e9ab11fcbe47d94cc27e8da05b24843c7 100644
--- a/Library/Homebrew/cask/staged.rb
+++ b/Library/Homebrew/cask/staged.rb
@@ -3,6 +3,9 @@
require "utils/user"
module Cask
+ # Helper functions for staged casks.
+ #
+ # @api private
module Staged
def set_permissions(paths, permissions_str)
full_paths = remove_nonexistent(paths)
diff --git a/Library/Homebrew/cask/topological_hash.rb b/Library/Homebrew/cask/topological_hash.rb
index 919dc161f71de35cd349434397625549838b74f2..bfd85738273aa8f6cbd550bf0568027e1f47922d 100644
--- a/Library/Homebrew/cask/topological_hash.rb
+++ b/Library/Homebrew/cask/topological_hash.rb
@@ -2,8 +2,8 @@
require "tsort"
-# a basic topologically sortable hashmap
module Cask
+ # Topologically sortable hash map.
class TopologicalHash < Hash
include TSort
diff --git a/Library/Homebrew/cask/url.rb b/Library/Homebrew/cask/url.rb
index ad7c3506e7b1b703f74be20b130dc9735f54678d..2e59372f9d1a48ca890e189278bb58eb90804979 100644
--- a/Library/Homebrew/cask/url.rb
+++ b/Library/Homebrew/cask/url.rb
@@ -1,5 +1,8 @@
# frozen_string_literal: true
+# Class corresponding to the `url` stanza.
+#
+# @api private
class URL
ATTRIBUTES = [
:using,
@@ -7,6 +10,7 @@ class URL
:trust_cert, :cookies, :referer, :user_agent,
:data
].freeze
+ private_constant :ATTRIBUTES
attr_reader :uri, :specs, *ATTRIBUTES
diff --git a/Library/Homebrew/cask/utils.rb b/Library/Homebrew/cask/utils.rb
index a4b521bc2ea297fcd16b29cce1fcc471b0e02d69..8cee5976004d89718914bd224476de2199da6d15 100644
--- a/Library/Homebrew/cask/utils.rb
+++ b/Library/Homebrew/cask/utils.rb
@@ -8,6 +8,9 @@ require "stringio"
BUG_REPORTS_URL = "https://github.com/Homebrew/homebrew-cask#reporting-bugs"
module Cask
+ # Helper functions for various cask operations.
+ #
+ # @api private
module Utils
def self.gain_permissions_remove(path, command: SystemCommand)
if path.respond_to?(:rmtree) && path.exist?
diff --git a/Library/Homebrew/cask/verify.rb b/Library/Homebrew/cask/verify.rb
index ca0c0ddeeaf6cbde5707db6e387ec5bbd999ce24..f31d234c42fa8e0f7d4d421221ec5717e18c61e5 100644
--- a/Library/Homebrew/cask/verify.rb
+++ b/Library/Homebrew/cask/verify.rb
@@ -1,6 +1,9 @@
# frozen_string_literal: true
module Cask
+ # Helper module for verifying a cask's checksum.
+ #
+ # @api private
module Verify
module_function
diff --git a/Library/Homebrew/caveats.rb b/Library/Homebrew/caveats.rb
index 1b4e96d5e6ed4a7863e68a46340d2a38a455c062..01ad2bd278a2991c262fe3f243b04afb2626b5f5 100644
--- a/Library/Homebrew/caveats.rb
+++ b/Library/Homebrew/caveats.rb
@@ -2,6 +2,9 @@
require "language/python"
+# A formula's caveats.
+#
+# @api private
class Caveats
extend Forwardable
diff --git a/Library/Homebrew/checksum.rb b/Library/Homebrew/checksum.rb
index fe0960df4ac27fe03ab1bbf6ee46ec93adee1dee..84c6c62342808b6bf7dcaeee06aebceb567d0071 100644
--- a/Library/Homebrew/checksum.rb
+++ b/Library/Homebrew/checksum.rb
@@ -1,5 +1,8 @@
# frozen_string_literal: true
+# A formula's checksum.
+#
+# @api private
class Checksum
extend Forwardable
diff --git a/Library/Homebrew/cli/named_args.rb b/Library/Homebrew/cli/named_args.rb
index 2597f4ba51445dd483929975bdea35ea4f044224..f6db49c90a645ad1760e09b7be9a74f3e3d00a78 100644
--- a/Library/Homebrew/cli/named_args.rb
+++ b/Library/Homebrew/cli/named_args.rb
@@ -6,6 +6,9 @@ require "formulary"
module Homebrew
module CLI
+ # Helper class for loading formulae/casks from named arguments.
+ #
+ # @api private
class NamedArgs < SimpleDelegator
def initialize(*args, override_spec: nil, force_bottle: false, flags: [])
@args = args
diff --git a/Library/Homebrew/commands.rb b/Library/Homebrew/commands.rb
index fe279bb7778aa62465d645971333044cda12baf2..30098ae92bcd3ed1304f11ade453f7f3198387a0 100644
--- a/Library/Homebrew/commands.rb
+++ b/Library/Homebrew/commands.rb
@@ -2,6 +2,9 @@
require "cask/cmd"
+# Helper functions for commands.
+#
+# @api private
module Commands
module_function
diff --git a/Library/Homebrew/compilers.rb b/Library/Homebrew/compilers.rb
index 25a9a42147f3d9d2fefa559d26f08283eedc3c75..ca19f896f54987175cc04c7de4d9e94d9e8b2059 100644
--- a/Library/Homebrew/compilers.rb
+++ b/Library/Homebrew/compilers.rb
@@ -14,6 +14,9 @@ module CompilerConstants
GNU_GCC_VERSIONS.map { |n| "gcc-#{n}" }).freeze
end
+# Class for checking compiler compatibility for a formula.
+#
+# @api private
class CompilerFailure
attr_reader :name
@@ -70,6 +73,9 @@ class CompilerFailure
}.freeze
end
+# Class for selecting a compiler for a formula.
+#
+# @api private
class CompilerSelector
include CompilerConstants
diff --git a/Library/Homebrew/context.rb b/Library/Homebrew/context.rb
index c8c70ac7b8159c02cc9eccb665d0e44abce2eaa0..46407ed5bbaea6cf0a6e10bf86b286dfcbf523b2 100644
--- a/Library/Homebrew/context.rb
+++ b/Library/Homebrew/context.rb
@@ -2,6 +2,9 @@
require "monitor"
+# Module for querying the current execution context.
+#
+# @api private
module Context
extend MonitorMixin
@@ -21,6 +24,7 @@ module Context
end
end
+ # Struct describing the current execution context.
class ContextStruct
def initialize(debug: nil, quiet: nil, verbose: nil)
@debug = debug
diff --git a/Library/Homebrew/debrew.rb b/Library/Homebrew/debrew.rb
index 33209cffe1ccc0fd9937bdc78eb3f9582c669f8e..6382cbca0c3cdddb26e8de3342bb748d38ef5659 100644
--- a/Library/Homebrew/debrew.rb
+++ b/Library/Homebrew/debrew.rb
@@ -3,11 +3,15 @@
require "mutex_m"
require "debrew/irb"
+# Helper module for debugging formulae.
+#
+# @api private
module Debrew
extend Mutex_m
Ignorable = Module.new.freeze
+ # Module for allowing to ignore exceptions.
module Raise
def raise(*)
super
@@ -19,6 +23,7 @@ module Debrew
alias fail raise
end
+ # Module for allowing to debug formulae.
module Formula
def install
Debrew.debrew { super }
@@ -33,6 +38,7 @@ module Debrew
end
end
+ # Module for displaying a debugging menu.
class Menu
Entry = Struct.new(:name, :action)
diff --git a/Library/Homebrew/dependable.rb b/Library/Homebrew/dependable.rb
index 2b97e7db75216c4fbfb639ade3196755e64f01fc..89dfe083c2350e54069dbfb86835e68416c5945b 100644
--- a/Library/Homebrew/dependable.rb
+++ b/Library/Homebrew/dependable.rb
@@ -2,6 +2,9 @@
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 them being
# misused in future.
diff --git a/Library/Homebrew/dependencies.rb b/Library/Homebrew/dependencies.rb
index 476d1b53ec2c3682daea7b87a869c1a314d1fac8..6a39871b13443747d1ba30ea1bbbaa855fce2c30 100644
--- a/Library/Homebrew/dependencies.rb
+++ b/Library/Homebrew/dependencies.rb
@@ -3,6 +3,9 @@
require "delegate"
require "cask_dependent"
+# A collection of dependencies.
+#
+# @api private
class Dependencies < DelegateClass(Array)
def initialize(*args)
super(args)
@@ -35,6 +38,9 @@ class Dependencies < DelegateClass(Array)
end
end
+# A collection of requirements.
+#
+# @api private
class Requirements < DelegateClass(Set)
def initialize(*args)
super(Set.new(args))
diff --git a/Library/Homebrew/dependencies_helpers.rb b/Library/Homebrew/dependencies_helpers.rb
index fb6f13e9d1f8bf5952ed36d963d6153186dd4456..998cef14a2013ec82bf87e0005be3ede8143f3f0 100644
--- a/Library/Homebrew/dependencies_helpers.rb
+++ b/Library/Homebrew/dependencies_helpers.rb
@@ -2,6 +2,9 @@
require "cask_dependent"
+# Helper functions for dependencies.
+#
+# @api private
module DependenciesHelpers
def args_includes_ignores(args)
includes = []
diff --git a/Library/Homebrew/dependency.rb b/Library/Homebrew/dependency.rb
index d97a5a22a1e1aaac0665284b340615491e1b692d..29a2284c7fe2fb9068a219346c38a37c400cf599 100644
--- a/Library/Homebrew/dependency.rb
+++ b/Library/Homebrew/dependency.rb
@@ -3,6 +3,8 @@
require "dependable"
# A dependency on another Homebrew formula.
+#
+# @api private
class Dependency
extend Forwardable
include Dependable
@@ -10,6 +12,7 @@ class Dependency
attr_reader :name, :tags, :env_proc, :option_names
DEFAULT_ENV_PROC = proc {}.freeze
+ private_constant :DEFAULT_ENV_PROC
def initialize(name, tags = [], env_proc = DEFAULT_ENV_PROC, option_names = [name])
raise ArgumentError, "Dependency must have a name!" unless name
@@ -176,6 +179,7 @@ class Dependency
end
end
+# A dependency on another Homebrew formula in a specific tap.
class TapDependency < Dependency
attr_reader :tap
diff --git a/Library/Homebrew/descriptions.rb b/Library/Homebrew/descriptions.rb
index 46b7f2ef317da2a38110ff4047eb554c70f4315c..6ba21bed47e269dd44970ceca20ecb580cc13da2 100644
--- a/Library/Homebrew/descriptions.rb
+++ b/Library/Homebrew/descriptions.rb
@@ -5,6 +5,9 @@ require "formula_versions"
require "search"
require "searchable"
+# Helper class for printing and searching descriptions.
+#
+# @api private
class Descriptions
extend Homebrew::Search
diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb
index f6a578b1acaa77ff74e07d74eb7d896e5733541c..a8cc41682fe91247d0300b7e908f1514ccf5e3ed 100644
--- a/Library/Homebrew/env_config.rb
+++ b/Library/Homebrew/env_config.rb
@@ -1,6 +1,9 @@
# frozen_string_literal: true
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 d0016cb1e27826b0c9f4e224b43d7dad449c8216..137f593c71423bb9407c10a25cfe0a5aafaf7704 100644
--- a/Library/Homebrew/exceptions.rb
+++ b/Library/Homebrew/exceptions.rb
@@ -3,6 +3,7 @@
require "shellwords"
require "utils"
+# Raised when a command is used wrong.
class UsageError < RuntimeError
attr_reader :reason
@@ -19,12 +20,14 @@ class UsageError < RuntimeError
end
end
+# Raised when a command expects a formula and none was specified.
class FormulaUnspecifiedError < UsageError
def initialize
super "this command requires a formula argument"
end
end
+# Raised when a command expects a keg and none was specified.
class KegUnspecifiedError < UsageError
def initialize
super "this command requires a keg argument"
@@ -35,6 +38,7 @@ class MultipleVersionsInstalledError < RuntimeError; end
class NotAKegError < RuntimeError; end
+# Raised when a keg doesn't exist.
class NoSuchKegError < RuntimeError
attr_reader :name
@@ -44,6 +48,7 @@ class NoSuchKegError < RuntimeError
end
end
+# Raised when an invalid attribute is used in a formula.
class FormulaValidationError < StandardError
attr_reader :attr, :formula
@@ -56,10 +61,14 @@ end
class FormulaSpecificationError < StandardError; end
+# Raised when a deprecated method is used.
+#
+# @api private
class MethodDeprecatedError < StandardError
attr_accessor :issues_url
end
+# Raised when a formula is not available.
class FormulaUnavailableError < RuntimeError
attr_reader :name
attr_accessor :dependent
@@ -79,6 +88,9 @@ class FormulaUnavailableError < RuntimeError
end
end
+# Shared methods for formula class errors.
+#
+# @api private
module FormulaClassUnavailableErrorModule
attr_reader :path, :class_name, :class_list
@@ -107,6 +119,7 @@ module FormulaClassUnavailableErrorModule
end
end
+# Raised when a formula does not contain a formula class.
class FormulaClassUnavailableError < FormulaUnavailableError
include FormulaClassUnavailableErrorModule
@@ -118,6 +131,9 @@ class FormulaClassUnavailableError < FormulaUnavailableError
end
end
+# Shared methods for formula unreadable errors.
+#
+# @api private
module FormulaUnreadableErrorModule
attr_reader :formula_error
@@ -126,6 +142,7 @@ module FormulaUnreadableErrorModule
end
end
+# Raised when a formula is unreadable.
class FormulaUnreadableError < FormulaUnavailableError
include FormulaUnreadableErrorModule
@@ -135,6 +152,7 @@ class FormulaUnreadableError < FormulaUnavailableError
end
end
+# Raised when a formula in a specific tap is unavailable.
class TapFormulaUnavailableError < FormulaUnavailableError
attr_reader :tap, :user, :repo
@@ -152,6 +170,7 @@ class TapFormulaUnavailableError < FormulaUnavailableError
end
end
+# Raised when a formula in a specific tap does not contain a formula class.
class TapFormulaClassUnavailableError < TapFormulaUnavailableError
include FormulaClassUnavailableErrorModule
@@ -165,6 +184,7 @@ class TapFormulaClassUnavailableError < TapFormulaUnavailableError
end
end
+# Raised when a formula in a specific tap is unreadable.
class TapFormulaUnreadableError < TapFormulaUnavailableError
include FormulaUnreadableErrorModule
@@ -174,6 +194,7 @@ class TapFormulaUnreadableError < TapFormulaUnavailableError
end
end
+# Raised when a formula with the same name is found multiple taps.
class TapFormulaAmbiguityError < RuntimeError
attr_reader :name, :paths, :formulae
@@ -192,6 +213,7 @@ class TapFormulaAmbiguityError < RuntimeError
end
end
+# Raised when a formula's old name in a specific tap is found in multiple taps.
class TapFormulaWithOldnameAmbiguityError < RuntimeError
attr_reader :name, :possible_tap_newname_formulae, :taps
@@ -212,6 +234,7 @@ class TapFormulaWithOldnameAmbiguityError < RuntimeError
end
end
+# Raised when a tap is unavailable.
class TapUnavailableError < RuntimeError
attr_reader :name
@@ -224,6 +247,7 @@ class TapUnavailableError < RuntimeError
end
end
+# Raised when a tap's remote does not match the actual remote.
class TapRemoteMismatchError < RuntimeError
attr_reader :name, :expected_remote, :actual_remote
@@ -239,6 +263,7 @@ class TapRemoteMismatchError < RuntimeError
end
end
+# Raised when a tap is already installed.
class TapAlreadyTappedError < RuntimeError
attr_reader :name
@@ -251,6 +276,7 @@ class TapAlreadyTappedError < RuntimeError
end
end
+# Raised when another Homebrew operation is already in progress.
class OperationInProgressError < RuntimeError
def initialize(name)
message = <<~EOS
@@ -265,12 +291,14 @@ end
class CannotInstallFormulaError < RuntimeError; end
+# Raised when a formula installation was already attempted.
class FormulaInstallationAlreadyAttemptedError < RuntimeError
def initialize(formula)
super "Formula installation already attempted: #{formula.full_name}"
end
end
+# Raised when there are unsatisfied requirements.
class UnsatisfiedRequirements < RuntimeError
def initialize(reqs)
if reqs.length == 1
@@ -281,6 +309,7 @@ class UnsatisfiedRequirements < RuntimeError
end
end
+# Raised when a formula conflicts with another one.
class FormulaConflictError < RuntimeError
attr_reader :formula, :conflicts
@@ -313,6 +342,7 @@ class FormulaConflictError < RuntimeError
end
end
+# Raise when the Python version cannot be detected automatically.
class FormulaUnknownPythonError < RuntimeError
def initialize(formula)
super <<~EOS
@@ -325,6 +355,7 @@ class FormulaUnknownPythonError < RuntimeError
end
end
+# Raise when two Python versions are detected simultaneously.
class FormulaAmbiguousPythonError < RuntimeError
def initialize(formula)
super <<~EOS
@@ -336,6 +367,7 @@ class FormulaAmbiguousPythonError < RuntimeError
end
end
+# Raised when an error occurs during a formula build.
class BuildError < RuntimeError
attr_reader :cmd, :args, :env
attr_accessor :formula, :options
@@ -561,12 +593,14 @@ class ChecksumMismatchError < RuntimeError
end
end
+# Raised when a resource is missing.
class ResourceMissingError < ArgumentError
def initialize(formula, resource)
super "#{formula.full_name} does not define resource #{resource.inspect}"
end
end
+# Raised when a resource is specified multiple times.
class DuplicateResourceError < ArgumentError
def initialize(resource)
super "Resource #{resource.inspect} is defined more than once"
@@ -576,6 +610,7 @@ end
# Raised when a single patch file is not found and apply hasn't been specified.
class MissingApplyError < RuntimeError; end
+# Raised when a bottle does not contain a formula file.
class BottleFormulaUnavailableError < RuntimeError
def initialize(bottle_path, formula_path)
super <<~EOS
@@ -604,6 +639,7 @@ class ChildProcessError < RuntimeError
end
end
+# Raised when a macOS version is unsupported.
class MacOSVersionError < RuntimeError
attr_reader :version
diff --git a/Library/Homebrew/fetch.rb b/Library/Homebrew/fetch.rb
index 7b0e76cd85b7860e82ced859415c5f74e5da6362..717537cbc15fc4e90d4fd872c34940607c32ef10 100644
--- a/Library/Homebrew/fetch.rb
+++ b/Library/Homebrew/fetch.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module Homebrew
+ # @api private
module Fetch
def fetch_bottle?(f, args:)
return true if args.force_bottle? && f.bottle
diff --git a/Library/Homebrew/formula_assertions.rb b/Library/Homebrew/formula_assertions.rb
index 55592f2214bcb2bde49ac957057287c0babe6fca..fdcfa865739995a9a781ec2bd7ed3a3354caa9f1 100644
--- a/Library/Homebrew/formula_assertions.rb
+++ b/Library/Homebrew/formula_assertions.rb
@@ -1,6 +1,9 @@
# frozen_string_literal: true
module Homebrew
+ # Helper functions available in formula `test` blocks.
+ #
+ # @api private
module Assertions
include Context
@@ -8,6 +11,7 @@ module Homebrew
include ::Test::Unit::Assertions
# Returns the output of running cmd, and asserts the exit status
+ # @api public
def shell_output(cmd, result = 0)
ohai cmd
output = `#{cmd}`
@@ -19,7 +23,8 @@ module Homebrew
end
# Returns the output of running the cmd with the optional input, and
- # optionally asserts the exit status
+ # optionally asserts the exit status.
+ # @api public
def pipe_output(cmd, input = nil, result = nil)
ohai cmd
output = IO.popen(cmd, "w+") do |pipe|
diff --git a/Library/Homebrew/formula_cellar_checks.rb b/Library/Homebrew/formula_cellar_checks.rb
index d81f6d70e7c2d550c8a62e6a8cc54ad30b1b5894..4bed3fc5696d9f7ea7fc55f404c742363e42a9db 100644
--- a/Library/Homebrew/formula_cellar_checks.rb
+++ b/Library/Homebrew/formula_cellar_checks.rb
@@ -2,6 +2,9 @@
require "utils/shell"
+# Checks to perform on a formula's cellar.
+#
+# @api private
module FormulaCellarChecks
def check_env_path(bin)
# warn the user if stuff was installed outside of their PATH
diff --git a/Library/Homebrew/formula_creator.rb b/Library/Homebrew/formula_creator.rb
index 0be15b4f881cba4e29c55f770f180dbbe1a3268a..4153c5e0967e50bda404c7b2a56163a27704caeb 100644
--- a/Library/Homebrew/formula_creator.rb
+++ b/Library/Homebrew/formula_creator.rb
@@ -4,6 +4,9 @@ require "digest"
require "erb"
module Homebrew
+ # Class for generating a formula from a template.
+ #
+ # @api private
class FormulaCreator
attr_reader :args, :url, :sha256, :desc, :homepage
attr_accessor :name, :version, :tap, :path, :mode, :license
diff --git a/Library/Homebrew/formula_free_port.rb b/Library/Homebrew/formula_free_port.rb
index 894b5cf8c23330cb08f3a4d686ba9ba8b1f965ba..2067ca287f4a1c108af9a5d2dd59913aa68d7ab7 100644
--- a/Library/Homebrew/formula_free_port.rb
+++ b/Library/Homebrew/formula_free_port.rb
@@ -1,9 +1,14 @@
# frozen_string_literal: true
+require "socket"
+
module Homebrew
+ # Helper function for finding a free port.
+ #
+ # @api private
module FreePort
- require "socket"
-
+ # Returns a free port.
+ # @api public
def free_port
server = TCPServer.new 0
_, port, = server.addr
diff --git a/Library/Homebrew/formula_info.rb b/Library/Homebrew/formula_info.rb
index 4243d6d39246529e18613da40f77caafbf76121a..916564394897651baa93b4e3e025762f401f2590 100644
--- a/Library/Homebrew/formula_info.rb
+++ b/Library/Homebrew/formula_info.rb
@@ -1,7 +1,8 @@
# frozen_string_literal: true
-# Formula info drawn from an external `brew info --json` call
-
+# 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 684ffa3bbe53327af790fc9fa8fbe4468658f103..0da32495f1c59bd420de810a0fba4a63247aed82 100644
--- a/Library/Homebrew/formula_installer.rb
+++ b/Library/Homebrew/formula_installer.rb
@@ -21,6 +21,9 @@ require "cmd/install"
require "find"
require "utils/spdx"
+# Installer for a formula.
+#
+# @api private
class FormulaInstaller
include FormulaCellarChecks
extend Predicable
diff --git a/Library/Homebrew/formula_pin.rb b/Library/Homebrew/formula_pin.rb
index f9c54097fa1d704a3258b36d07dae4ecf37a0722..613a51fc81a322aa05c1e8d4bff33e974eec75ae 100644
--- a/Library/Homebrew/formula_pin.rb
+++ b/Library/Homebrew/formula_pin.rb
@@ -2,6 +2,9 @@
require "keg"
+# Helper functions for pinning a formula.
+#
+# @api private
class FormulaPin
def initialize(f)
@f = f
diff --git a/Library/Homebrew/formula_versions.rb b/Library/Homebrew/formula_versions.rb
index 2fb219d85d606023caf787ba774ce1f62931a453..ecd67d52704d87d9a01ac67822f2af63bee11fde 100644
--- a/Library/Homebrew/formula_versions.rb
+++ b/Library/Homebrew/formula_versions.rb
@@ -2,6 +2,9 @@
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 c9e147a91ea69b8999ae3204e595fc427b893cd3..f71354f0895ae89ec2f77c63d3199e9e87cdf97e 100644
--- a/Library/Homebrew/formulary.rb
+++ b/Library/Homebrew/formulary.rb
@@ -6,7 +6,8 @@ require "tab"
# The Formulary is responsible for creating instances of {Formula}.
# It is not meant to be used directly from formulae.
-
+#
+# @api private
module Formulary
extend Cachable
@@ -150,7 +151,7 @@ module Formulary
end
end
- # Loads formulae from bottles.
+ # Loads a formula from a bottle.
class BottleLoader < FormulaLoader
def initialize(bottle_name)
case bottle_name
@@ -187,6 +188,7 @@ module Formulary
end
end
+ # Loads a formula from a path to an alias.
class AliasLoader < FormulaLoader
def initialize(alias_path)
path = alias_path.resolved_path
@@ -298,6 +300,7 @@ module Formulary
end
end
+ # Pseudo-loader which will raise a `FormulaUnavailableError` when trying to load the corresponding formula.
class NullLoader < FormulaLoader
def initialize(name)
super name, Formulary.core_path(name)
diff --git a/Library/Homebrew/install_renamed.rb b/Library/Homebrew/install_renamed.rb
index 9fa6f37fa22739a2c1417ca30f45a3d1b770f9c9..ac891273a090473ff19b34514bbfc3601dd83249 100644
--- a/Library/Homebrew/install_renamed.rb
+++ b/Library/Homebrew/install_renamed.rb
@@ -1,5 +1,8 @@
# 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/keg.rb b/Library/Homebrew/keg.rb
index 4698dcfa0c52c06bb1e539ca9d20f042636862fd..00668f1250fe6e64c4921ba99646affd78358cac 100644
--- a/Library/Homebrew/keg.rb
+++ b/Library/Homebrew/keg.rb
@@ -6,9 +6,13 @@ require "lock_file"
require "ostruct"
require "extend/cachable"
+# Installation prefix of a formula.
+#
+# @api private
class Keg
extend Cachable
+ # Error for when a keg is already linked.
class AlreadyLinkedError < RuntimeError
def initialize(keg)
super <<~EOS
@@ -18,6 +22,7 @@ class Keg
end
end
+ # Error for when a keg cannot be linked.
class LinkError < RuntimeError
attr_reader :keg, :src, :dst
@@ -31,6 +36,7 @@ class Keg
end
end
+ # Error for when a file already exists or belongs to another keg.
class ConflictError < LinkError
def suggestion
conflict = Keg.for(dst)
@@ -58,6 +64,7 @@ class Keg
end
end
+ # Error for when a directory is not writable.
class DirectoryNotWritableError < LinkError
def to_s
<<~EOS
diff --git a/Library/Homebrew/language/go.rb b/Library/Homebrew/language/go.rb
index 84188c0ef446aac76e98873e04c7c2b6948aa23a..2b4a0399d81b0b9a12c155688c247d9274539d9c 100644
--- a/Library/Homebrew/language/go.rb
+++ b/Library/Homebrew/language/go.rb
@@ -3,6 +3,9 @@
require "resource"
module Language
+ # Helper functions for Go formulae.
+ #
+ # @api public
module Go
# Given a set of resources, stages them to a gopath for
# building go software.
diff --git a/Library/Homebrew/language/java.rb b/Library/Homebrew/language/java.rb
index 1d2685d3fba353395bf443e87500dbb8e3bd0ca7..db9be69a22b1ce366613e2b0a9aa1ff9de8a6de3 100644
--- a/Library/Homebrew/language/java.rb
+++ b/Library/Homebrew/language/java.rb
@@ -1,6 +1,9 @@
# frozen_string_literal: true
module Language
+ # Helper functions for Java formulae.
+ #
+ # @api public
module Java
def self.find_openjdk_formula(version = nil)
can_be_newer = version&.end_with?("+")
diff --git a/Library/Homebrew/language/node.rb b/Library/Homebrew/language/node.rb
index 75d61f8a4edc464d6be6762644c04ac396fb5865..4f53e485f85cb1760c0c4514fb35bd90b6c89554 100644
--- a/Library/Homebrew/language/node.rb
+++ b/Library/Homebrew/language/node.rb
@@ -1,6 +1,9 @@
# frozen_string_literal: true
module Language
+ # Helper functions for Node formulae.
+ #
+ # @api public
module Node
def self.npm_cache_config
"cache=#{HOMEBREW_CACHE}/npm_cache"
diff --git a/Library/Homebrew/language/perl.rb b/Library/Homebrew/language/perl.rb
index 7368b36ee6a5c4bff868428247d86f704cca49b1..c81ef65c51208d26943b38a194cacf455153ecbd 100644
--- a/Library/Homebrew/language/perl.rb
+++ b/Library/Homebrew/language/perl.rb
@@ -1,7 +1,11 @@
# frozen_string_literal: true
module Language
+ # Helper functions for Perl formulae.
+ #
+ # @api public
module Perl
+ # Helper module for replacing `perl` shebangs.
module Shebang
module_function
diff --git a/Library/Homebrew/lazy_object.rb b/Library/Homebrew/lazy_object.rb
index d54f15ed7e91c242da3f4af314a438492553d8a0..8ea44995ebce29b2a0b35583da19564f2860212e 100644
--- a/Library/Homebrew/lazy_object.rb
+++ b/Library/Homebrew/lazy_object.rb
@@ -1,5 +1,8 @@
# frozen_string_literal: true
+# 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 65263161d9b5bd8f4b3810e7557433865e0d611b..9948086f22a654e9b9a12df74933bab862099f81 100644
--- a/Library/Homebrew/linkage_checker.rb
+++ b/Library/Homebrew/linkage_checker.rb
@@ -5,6 +5,9 @@ require "formula"
require "linkage_cache_store"
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/lock_file.rb b/Library/Homebrew/lock_file.rb
index 99c1afda5e2b9db9b27f3f61c66403d867b663b9..88f017a1702a1080cbc863323e4fdc233aa931e0 100644
--- a/Library/Homebrew/lock_file.rb
+++ b/Library/Homebrew/lock_file.rb
@@ -2,6 +2,9 @@
require "fcntl"
+# A lock file.
+#
+# @api private
class LockFile
attr_reader :path
@@ -43,12 +46,18 @@ class LockFile
end
end
+# A lock file for a formula.
+#
+# @api private
class FormulaLock < LockFile
def initialize(name)
super("#{name}.formula")
end
end
+# A lock file for a cask.
+#
+# @api private
class CaskLock < LockFile
def initialize(name)
super("#{name}.cask")
diff --git a/Library/Homebrew/metafiles.rb b/Library/Homebrew/metafiles.rb
index 5159623f1d6a307be3c823a8f5de22da556507bc..95404030ffe0c4f27f313c8ceeccd2f46bb2ca77 100644
--- a/Library/Homebrew/metafiles.rb
+++ b/Library/Homebrew/metafiles.rb
@@ -1,5 +1,8 @@
# frozen_string_literal: true
+# Helper for checking if a file is considered a metadata file.
+#
+# @api private
module Metafiles
# https://github.com/github/markup#markups
EXTENSIONS = Set.new(%w[
diff --git a/Library/Homebrew/migrator.rb b/Library/Homebrew/migrator.rb
index e0903aa48ffbd923d7b9cda3bd64203b8d23dbbe..bdf05f93bb766c4584ee7845cb6c75253a28828f 100644
--- a/Library/Homebrew/migrator.rb
+++ b/Library/Homebrew/migrator.rb
@@ -4,9 +4,13 @@ require "lock_file"
require "keg"
require "tab"
+# Helper class for migrating a formula from an old to a new name.
+#
+# @api private
class Migrator
include Context
+ # Error for when a migration is necessary.
class MigrationNeededError < RuntimeError
def initialize(formula)
super <<~EOS
@@ -16,18 +20,21 @@ class Migrator
end
end
+ # Error for when a formula does not replace another formula.
class MigratorNoOldnameError < RuntimeError
def initialize(formula)
super "#{formula.name} doesn't replace any formula."
end
end
+ # Error for when the old name's path does not exist.
class MigratorNoOldpathError < RuntimeError
def initialize(formula)
super "#{HOMEBREW_CELLAR/formula.oldname} doesn't exist."
end
end
+ # Error for when a formula is migrated to a different tap without explicitly using its fully-qualified name.
class MigratorDifferentTapsError < RuntimeError
def initialize(formula, tap)
msg = if tap.core_tap?
diff --git a/Library/Homebrew/missing_formula.rb b/Library/Homebrew/missing_formula.rb
index 8205a566344c380310caca0f3c044bec575b686a..c69de457bbf72a389a335fea2a900d1a48fd0217 100644
--- a/Library/Homebrew/missing_formula.rb
+++ b/Library/Homebrew/missing_formula.rb
@@ -3,6 +3,9 @@
require "formulary"
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/os.rb b/Library/Homebrew/os.rb
index ff739cd20f59e311b45b16b11035eac5ab6c8f72..4981f12b53e42fc8121e9ab89e53ad1e934de8af 100644
--- a/Library/Homebrew/os.rb
+++ b/Library/Homebrew/os.rb
@@ -1,18 +1,30 @@
# frozen_string_literal: true
+# Helper functions for querying operating system information.
+#
+# @api private
module OS
+ # Check if the operating system is macOS.
+ #
+ # @api public
def self.mac?
return false if ENV["HOMEBREW_TEST_GENERIC_OS"]
RbConfig::CONFIG["host_os"].include? "darwin"
end
+ # Check if the operating system is Linux.
+ #
+ # @api public
def self.linux?
return false if ENV["HOMEBREW_TEST_GENERIC_OS"]
RbConfig::CONFIG["host_os"].include? "linux"
end
+ # Get the kernel version.
+ #
+ # @api public
def self.kernel_version
@kernel_version ||= Version.new(Utils.safe_popen_read("uname", "-r").chomp)
end
diff --git a/Library/Homebrew/os/linux.rb b/Library/Homebrew/os/linux.rb
index da4b9d7acddc54cbe9faff25ddb32330535eb9ab..1e3cb24fa8968648b06dd9f8ff009ea91a8969eb 100644
--- a/Library/Homebrew/os/linux.rb
+++ b/Library/Homebrew/os/linux.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module OS
+ # Helper module for querying system information on Linux.
module Linux
module_function
@@ -21,7 +22,7 @@ module OS
end
end
- # Define OS::Mac on Linux for formula API compatibility.
+ # rubocop:disable Style/Documentation
module Mac
module_function
@@ -77,4 +78,5 @@ module OS
end
end
end
+ # rubocop:enable Style/Documentation
end
diff --git a/Library/Homebrew/os/linux/elf.rb b/Library/Homebrew/os/linux/elf.rb
index 05ebff0c3c6c65e93cf6640ae8e2b07ba3d7dba4..a0d84e7d4f31d8c61f5a2aa494230daa6ecbfaf7 100644
--- a/Library/Homebrew/os/linux/elf.rb
+++ b/Library/Homebrew/os/linux/elf.rb
@@ -1,24 +1,42 @@
# frozen_string_literal: true
+# {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
MAGIC_NUMBER_ASCII = "\x7fELF"
+ private_constant :MAGIC_NUMBER_ASCII
OS_ABI_OFFSET = 0x07
+ private_constant :OS_ABI_OFFSET
OS_ABI_SYSTEM_V = 0
+ private_constant :OS_ABI_SYSTEM_V
OS_ABI_LINUX = 3
+ private_constant :OS_ABI_LINUX
TYPE_OFFSET = 0x10
+ private_constant :TYPE_OFFSET
TYPE_EXECUTABLE = 2
+ private_constant :TYPE_EXECUTABLE
TYPE_SHARED = 3
+ private_constant :TYPE_SHARED
ARCHITECTURE_OFFSET = 0x12
+ private_constant :ARCHITECTURE_OFFSET
ARCHITECTURE_I386 = 0x3
+ private_constant :ARCHITECTURE_I386
ARCHITECTURE_POWERPC = 0x14
+ private_constant :ARCHITECTURE_POWERPC
ARCHITECTURE_ARM = 0x28
+ private_constant :ARCHITECTURE_ARM
ARCHITECTURE_X86_64 = 0x62
+ private_constant :ARCHITECTURE_X86_64
ARCHITECTURE_AARCH64 = 0xB7
+ private_constant :ARCHITECTURE_AARCH64
def read_uint8(offset)
read(1, offset).unpack1("C")
@@ -86,6 +104,9 @@ module ELFShim
@dynamic_elf = patchelf_patcher.elf.segment_by_type(:DYNAMIC).present?
end
+ # Helper class for reading metadata from an ELF file.
+ #
+ # @api private
class Metadata
attr_reader :path, :dylib_id, :dylibs
@@ -125,6 +146,7 @@ module ELFShim
[patcher.soname, patcher.needed]
end
end
+ private_constant :Metadata
def rpath_using_patchelf_rb
patchelf_patcher.runpath || patchelf_patcher.rpath
@@ -138,6 +160,7 @@ module ELFShim
def metadata
@metadata ||= Metadata.new(self)
end
+ private :metadata
def dylib_id
metadata.dylib_id
diff --git a/Library/Homebrew/os/linux/glibc.rb b/Library/Homebrew/os/linux/glibc.rb
index c7073b39f36739552fad350f11948297910227dc..a42ee092d0d5941faae750a8ef9c3e2c98076a8b 100644
--- a/Library/Homebrew/os/linux/glibc.rb
+++ b/Library/Homebrew/os/linux/glibc.rb
@@ -2,6 +2,9 @@
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 31680b9e7e4ea676eb3c06cfc88a4d10a7f6dc08..1c20ce5a141569e1888980b8c6bfb93a3987de9f 100644
--- a/Library/Homebrew/os/linux/kernel.rb
+++ b/Library/Homebrew/os/linux/kernel.rb
@@ -2,6 +2,9 @@
module OS
module Linux
+ # Helper functions for querying Linux kernel information.
+ #
+ # @api private
module Kernel
module_function
diff --git a/Library/Homebrew/os/mac.rb b/Library/Homebrew/os/mac.rb
index b44a47bcc441e1482cd44262819ceef29ff45e95..8e9d0d33f31f048d1546545d8f45f1f0967f47b2 100644
--- a/Library/Homebrew/os/mac.rb
+++ b/Library/Homebrew/os/mac.rb
@@ -7,6 +7,7 @@ require "os/mac/sdk"
require "os/mac/keg"
module OS
+ # Helper module for querying system information on macOS.
module Mac
module_function
diff --git a/Library/Homebrew/os/mac/mach.rb b/Library/Homebrew/os/mac/mach.rb
index 93cab7de4f55f2c0462822f2ee0d9d2b2225a20f..aef81642682611eb57202802f67a079d3ae1903b 100644
--- a/Library/Homebrew/os/mac/mach.rb
+++ b/Library/Homebrew/os/mac/mach.rb
@@ -3,19 +3,21 @@
require "macho"
require "os/mac/architecture_list"
+# {Pathname} extension for dealing with Mach-O files.
+#
+# @api private
module MachOShim
extend Forwardable
delegate [:dylib_id, :rpaths, :delete_rpath] => :macho
- # @private
def macho
@macho ||= begin
MachO.open(to_s)
end
end
+ private :macho
- # @private
def mach_data
@mach_data ||= begin
machos = []
@@ -55,6 +57,7 @@ module MachOShim
[]
end
end
+ private :mach_data
def dynamically_linked_libraries(except: :none)
lcs = macho.dylib_load_commands.reject { |lc| lc.type == except }
@@ -94,19 +97,16 @@ module MachOShim
arch == :ppc64
end
- # @private
def dylib?
mach_data.any? { |m| m.fetch(:type) == :dylib }
end
- # @private
def mach_o_executable?
mach_data.any? { |m| m.fetch(:type) == :executable }
end
alias binary_executable? mach_o_executable?
- # @private
def mach_o_bundle?
mach_data.any? { |m| m.fetch(:type) == :bundle }
end
diff --git a/Library/Homebrew/os/mac/sdk.rb b/Library/Homebrew/os/mac/sdk.rb
index f6061c3712cc68901c07e69d54fc36efb7a45640..54bed4fabb1086a0ff79119a45fb436f92157d3b 100644
--- a/Library/Homebrew/os/mac/sdk.rb
+++ b/Library/Homebrew/os/mac/sdk.rb
@@ -4,6 +4,9 @@ require "os/mac/version"
module OS
module Mac
+ # Class representing a macOS SDK.
+ #
+ # @api private
class SDK
attr_reader :version, :path, :source
@@ -14,6 +17,9 @@ module OS
end
end
+ # Base class for SDK locators.
+ #
+ # @api private
class BaseSDKLocator
class NoSDKError < StandardError; end
@@ -42,7 +48,7 @@ module OS
else
sdk_for v
end
- rescue BaseSDKLocator::NoSDKError
+ rescue NoSDKError
latest_sdk
end
# Only return an SDK older than the OS version if it was specifically requested
@@ -79,7 +85,11 @@ module OS
end
end
end
+ private_constant :BaseSDKLocator
+ # Helper class for locating the Xcode SDK.
+ #
+ # @api private
class XcodeSDKLocator < BaseSDKLocator
def source
:xcode
@@ -100,6 +110,9 @@ module OS
end
end
+ # Helper class for locating the macOS Command Line Tools SDK.
+ #
+ # @api private
class CLTSDKLocator < BaseSDKLocator
def source
:clt
diff --git a/Library/Homebrew/os/mac/version.rb b/Library/Homebrew/os/mac/version.rb
index 2134637344df5fd17301757b5f1128d51e1ffdb3..1c47f9ee8837dc6a480e0867aa96d092265a865b 100644
--- a/Library/Homebrew/os/mac/version.rb
+++ b/Library/Homebrew/os/mac/version.rb
@@ -5,6 +5,9 @@ require "version"
module OS
module Mac
+ # A macOS version.
+ #
+ # @api private
class Version < ::Version
SYMBOLS = {
big_sur: "11.0",
diff --git a/Library/Homebrew/os/mac/xcode.rb b/Library/Homebrew/os/mac/xcode.rb
index 5f1a23d66369a74461886993d9fb0614eefab393..9aa9ba746de5ab48faec0fba7ef8bdc094414356 100644
--- a/Library/Homebrew/os/mac/xcode.rb
+++ b/Library/Homebrew/os/mac/xcode.rb
@@ -2,6 +2,9 @@
module OS
module Mac
+ # Helper module for querying Xcode information.
+ #
+ # @api private
module Xcode
module_function
@@ -200,6 +203,9 @@ module OS
end
end
+ # Helper module for querying macOS Command Line Tools information.
+ #
+ # @api private
module CLT
module_function
diff --git a/Library/Homebrew/patch.rb b/Library/Homebrew/patch.rb
index f2a92a06167c2c5afd8b12214c652d56baf2c402..de60b4a87bad00ec1f7ee1035aecb4aa590e47b2 100644
--- a/Library/Homebrew/patch.rb
+++ b/Library/Homebrew/patch.rb
@@ -3,6 +3,9 @@
require "resource"
require "erb"
+# Helper module for creating patches.
+#
+# @api private
module Patch
def self.create(strip, src, &block)
case strip
@@ -52,6 +55,9 @@ module Patch
end
end
+# An abstract class representing a patch embedded into a formula.
+#
+# @api private
class EmbeddedPatch
attr_writer :owner
attr_reader :strip
@@ -77,6 +83,9 @@ class EmbeddedPatch
end
end
+# A patch at the `__END__` of a formula file.
+#
+# @api private
class DATAPatch < EmbeddedPatch
attr_accessor :path
@@ -100,6 +109,9 @@ class DATAPatch < EmbeddedPatch
end
end
+# A string containing a patch.
+#
+# @api private
class StringPatch < EmbeddedPatch
def initialize(strip, str)
super(strip)
@@ -111,6 +123,9 @@ class StringPatch < EmbeddedPatch
end
end
+# A string containing a patch.
+#
+# @api private
class ExternalPatch
extend Forwardable
@@ -170,7 +185,11 @@ class ExternalPatch
end
end
+# A legacy patch.
+#
# Legacy patches have no checksum and are not cached.
+#
+# @api private
class LegacyPatch < ExternalPatch
def initialize(strip, url)
odeprecated "legacy patches", "'patch do' blocks"
diff --git a/Library/Homebrew/readall.rb b/Library/Homebrew/readall.rb
index 491c406cbb501ef7fc635dae188ac3954b30475d..d1e0a007bf5ac1504546dab0c39a37e99347f6a2 100644
--- a/Library/Homebrew/readall.rb
+++ b/Library/Homebrew/readall.rb
@@ -3,6 +3,9 @@
require "formula"
require "cask/cask_loader"
+# Helper module for validating syntax in taps.
+#
+# @api private
module Readall
class << self
def valid_ruby_syntax?(ruby_files)
diff --git a/Library/Homebrew/requirement.rb b/Library/Homebrew/requirement.rb
index 693c749a0d444f28fd1e7462d0ba5d4d499fa9b7..d4bb330119746ec4d04b15a7221297d94ebaa0bb 100644
--- a/Library/Homebrew/requirement.rb
+++ b/Library/Homebrew/requirement.rb
@@ -6,8 +6,10 @@ require "dependencies"
require "build_environment"
# 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.
+# 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
@@ -162,7 +164,7 @@ class Requirement
return @satisfied if options.nil? && !block_given?
options = {} if options.nil?
- @satisfied = Requirement::Satisfier.new(options, &block)
+ @satisfied = Satisfier.new(options, &block)
end
def env(*settings, &block)
@@ -174,6 +176,7 @@ class Requirement
end
end
+ # Helper class for evaluating whether a requirement is satisfied.
class Satisfier
def initialize(options, &block)
case options
@@ -201,6 +204,7 @@ class Requirement
end
end
end
+ private_constant :Satisfier
class << self
# Expand the requirements of dependent recursively, optionally yielding
diff --git a/Library/Homebrew/requirements/arch_requirement.rb b/Library/Homebrew/requirements/arch_requirement.rb
index 03a988c76bc59b1fdc4c59fb9979ff47f666e849..dc9d81320f6e9af02204c7eaf6d98b985bf4e532 100644
--- a/Library/Homebrew/requirements/arch_requirement.rb
+++ b/Library/Homebrew/requirements/arch_requirement.rb
@@ -2,6 +2,9 @@
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 b3643e6f233048c23753334d73936f83efbc87bf..dbec98dba9d126028c89fbeb381d9dc2d9cbbd97 100644
--- a/Library/Homebrew/requirements/codesign_requirement.rb
+++ b/Library/Homebrew/requirements/codesign_requirement.rb
@@ -1,5 +1,8 @@
# frozen_string_literal: true
+# A requirement on a code-signing identity.
+#
+# @api private
class CodesignRequirement < Requirement
fatal true
diff --git a/Library/Homebrew/requirements/java_requirement.rb b/Library/Homebrew/requirements/java_requirement.rb
index a2e4fa2d9e5b115646ad1031636c76b037cadb99..d6ba1a9332936f79d54562bc9c0efc1aa590068a 100644
--- a/Library/Homebrew/requirements/java_requirement.rb
+++ b/Library/Homebrew/requirements/java_requirement.rb
@@ -2,6 +2,9 @@
require "language/java"
+# A requirement on Java.
+#
+# @api private
class JavaRequirement < Requirement
fatal true
diff --git a/Library/Homebrew/requirements/linux_requirement.rb b/Library/Homebrew/requirements/linux_requirement.rb
index 74daf4cf4ae736fc52b01d59e9fbff4b80b97e5c..04b644a398f8434c3b5b50a739067771825c588e 100644
--- a/Library/Homebrew/requirements/linux_requirement.rb
+++ b/Library/Homebrew/requirements/linux_requirement.rb
@@ -1,5 +1,8 @@
# 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 a723dda2c689f1728cc82a0bcd5b4accb49c9bb9..f8bdcf9150ec615756ad6acc6fdf8468375a2b45 100644
--- a/Library/Homebrew/requirements/macos_requirement.rb
+++ b/Library/Homebrew/requirements/macos_requirement.rb
@@ -2,6 +2,9 @@
require "requirement"
+# A requirement on macOS.
+#
+# @api private
class MacOSRequirement < Requirement
fatal true
diff --git a/Library/Homebrew/requirements/osxfuse_requirement.rb b/Library/Homebrew/requirements/osxfuse_requirement.rb
index 79712de53c3dddcf5fdd55cb92d5afe1ffd33809..8371568fa095e63e2baf61d0bf0dc30996ff35a2 100644
--- a/Library/Homebrew/requirements/osxfuse_requirement.rb
+++ b/Library/Homebrew/requirements/osxfuse_requirement.rb
@@ -2,6 +2,9 @@
require "requirement"
+# A requirement on FUSE for macOS.
+#
+# @api private
class OsxfuseRequirement < Requirement
cask "osxfuse"
fatal true
diff --git a/Library/Homebrew/requirements/tuntap_requirement.rb b/Library/Homebrew/requirements/tuntap_requirement.rb
index 80b842977defb67fa351fa5efc4ec76da2780b24..6f9cec4cfd5fd78139fc467385ba646d6b6e520e 100644
--- a/Library/Homebrew/requirements/tuntap_requirement.rb
+++ b/Library/Homebrew/requirements/tuntap_requirement.rb
@@ -2,6 +2,9 @@
require "requirement"
+# A requirement on TunTap for macOS.
+#
+# @api private
class TuntapRequirement < Requirement
fatal true
cask "tuntap"
diff --git a/Library/Homebrew/requirements/x11_requirement.rb b/Library/Homebrew/requirements/x11_requirement.rb
index 58ecf33cf4e9bb6885f11bb77fc4c1008a21c804..f34834c2ffce447ae4521542c34dd4798602b9aa 100644
--- a/Library/Homebrew/requirements/x11_requirement.rb
+++ b/Library/Homebrew/requirements/x11_requirement.rb
@@ -2,6 +2,9 @@
require "requirement"
+# A requirement on X11.
+#
+# @api private
class X11Requirement < Requirement
include Comparable
diff --git a/Library/Homebrew/requirements/xcode_requirement.rb b/Library/Homebrew/requirements/xcode_requirement.rb
index 974de5f67ddad5db37d0b9901af6ec5d04a10799..97e1dde8da138737524b02cb5db64c6ec67868ad 100644
--- a/Library/Homebrew/requirements/xcode_requirement.rb
+++ b/Library/Homebrew/requirements/xcode_requirement.rb
@@ -2,6 +2,9 @@
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 e498069eaefe919163d915b22180977ab5d4e442..f4753914e09c9c92207d197c8abdd6c00b3013fe 100644
--- a/Library/Homebrew/resource.rb
+++ b/Library/Homebrew/resource.rb
@@ -8,6 +8,8 @@ require "mktemp"
# 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
include Context
include FileUtils
@@ -69,9 +71,11 @@ class Resource
end
# Verifies download and unpacks it.
- # The block may call `|resource,staging| staging.retain!` to retain the staging
+ # The block may call `|resource, staging| staging.retain!` to retain the staging
# directory. Subclasses that override stage should implement the tmp
# dir using {Mktemp} so that works with all subtypes.
+ #
+ # @api public
def stage(target = nil, &block)
raise ArgumentError, "target directory or block is required" if !target && block.blank?
@@ -211,12 +215,14 @@ class Resource
end
end
+ # A resource containing a Go package.
class Go < Resource
def stage(target)
super(target/name)
end
end
+ # A resource containing a patch.
class PatchResource < Resource
attr_reader :patch_files
@@ -243,6 +249,8 @@ end
# 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/rubocops/caveats.rb b/Library/Homebrew/rubocops/caveats.rb
index 09233e48eae24be205b978bf6d91302086cd4ca0..f81c4fc26f28bd637cd4cea56f9654e8c59df589 100644
--- a/Library/Homebrew/rubocops/caveats.rb
+++ b/Library/Homebrew/rubocops/caveats.rb
@@ -5,6 +5,24 @@ require "rubocops/extend/formula"
module RuboCop
module Cop
module FormulaAudit
+ # This cop makes sure that caveats don't recommend unsupported or unsafe operations.
+ #
+ # @example
+ # # bad
+ # def caveats
+ # <<~EOS
+ # Use `setuid` to allow running the exeutable by non-root users.
+ # EOS
+ # end
+ #
+ # # good
+ # def caveats
+ # <<~EOS
+ # 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 4feff95e1afaae8077db86a4e9220b7ce137e0d8..fda9de60d1349d40991d8b7e0b9c4ce08225a525 100644
--- a/Library/Homebrew/rubocops/checksum.rb
+++ b/Library/Homebrew/rubocops/checksum.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
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?
@@ -39,6 +42,9 @@ module RuboCop
end
end
+ # This cop makes sure that checksums strings are lowercase.
+ #
+ # @api private
class ChecksumCase < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
return if body_node.nil?
diff --git a/Library/Homebrew/rubocops/class.rb b/Library/Homebrew/rubocops/class.rb
index 7fde505269703366173bb641981e60355e330e1a..56ce23cff1c56cfdc52ee8d04b687a3bbea2d7e5 100644
--- a/Library/Homebrew/rubocops/class.rb
+++ b/Library/Homebrew/rubocops/class.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
module RuboCop
module Cop
module FormulaAudit
+ # This cop makes sure that `Formula` is used as superclass.
+ #
+ # @api private
class ClassName < FormulaCop
DEPRECATED_CLASSES = %w[
GithubGistFormula
@@ -26,6 +29,9 @@ module RuboCop
end
end
+ # This cop makes sure that a `test` block contains a proper test.
+ #
+ # @api private
class Test < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
test = find_block(body_node, :test)
@@ -78,7 +84,9 @@ module RuboCop
end
module FormulaAuditStrict
- # - `test do ..end` should defined in the formula.
+ # 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 d0d6298d50cfabb2c1cdb870aec71f562a4c090d..695971e0cd7884ce37192d9db3fc45adc89ddb76 100644
--- a/Library/Homebrew/rubocops/components_redundancy.rb
+++ b/Library/Homebrew/rubocops/components_redundancy.rb
@@ -5,13 +5,14 @@ require "rubocops/extend/formula"
module RuboCop
module Cop
module FormulaAudit
- # This cop checks if redundant components are present and other component errors.
+ # This cop checks if redundant components are present and for other component errors.
#
# - `url|checksum|mirror` should be inside `stable` block
# - `head` and `head do` should not be simultaneously present
# - `bottle :unneeded`/`:disable` and `bottle do` should not be simultaneously present
# - `stable do` should not be present without a `head` or `devel` spec
-
+ #
+ # @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.rb b/Library/Homebrew/rubocops/extend/formula.rb
index 8f165acc68edcefc3831726d26b50d777d3fafa2..80819e92f2225f3c7cba098bce92e83ae6c11e01 100644
--- a/Library/Homebrew/rubocops/extend/formula.rb
+++ b/Library/Homebrew/rubocops/extend/formula.rb
@@ -14,6 +14,9 @@ require "rubocops/shared/helper_functions"
module RuboCop
module Cop
+ # Superclass for all formula cops.
+ #
+ # @api private
class FormulaCop < Cop
include RangeHelp
include HelperFunctions
diff --git a/Library/Homebrew/rubocops/files.rb b/Library/Homebrew/rubocops/files.rb
index 843972daca73a9b7f57058063e9cf001e0c40918..d4454ad4cb9fb39798117a0827d3186df7dd4681 100644
--- a/Library/Homebrew/rubocops/files.rb
+++ b/Library/Homebrew/rubocops/files.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
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/keg_only.rb b/Library/Homebrew/rubocops/keg_only.rb
index 820bf795417932ae3de7a5ad9cfa1475be9e1ac1..6a578b5f7c0f8aeae9714c0fedde7d3533eb35c7 100644
--- a/Library/Homebrew/rubocops/keg_only.rb
+++ b/Library/Homebrew/rubocops/keg_only.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
module RuboCop
module Cop
module FormulaAudit
+ # This cop makes sure that a `keg_only` reason has the correct format.
+ #
+ # @api private
class KegOnly < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
keg_only_node = find_node_method_by_name(body_node, :keg_only)
diff --git a/Library/Homebrew/rubocops/lines.rb b/Library/Homebrew/rubocops/lines.rb
index a29092b4250b354c00f425eb2df1864b79de5fa9..158a7b8c60ac5801ebbb9a543c7fc58bd945c148 100644
--- a/Library/Homebrew/rubocops/lines.rb
+++ b/Library/Homebrew/rubocops/lines.rb
@@ -6,6 +6,8 @@ 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,
@@ -26,6 +28,9 @@ module RuboCop
end
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)
@@ -37,6 +42,9 @@ module RuboCop
end
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|
@@ -76,6 +84,9 @@ module RuboCop
end
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)
find_every_method_call_by_name(body_node, :assert).each do |method|
@@ -98,6 +109,9 @@ module RuboCop
end
end
+ # This cop makes sure that options are used idiomatically.
+ #
+ # @api private
class OptionDeclarations < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
problem "Use new-style option definitions" if find_method_def(body_node, :options)
@@ -178,6 +192,9 @@ module RuboCop
EOS
end
+ # This cop makes sure that formulae depend on `open-mpi` instead of `mpich`.
+ #
+ # @api private
class MpiCheck < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
# Enforce use of OpenMPI for MPI dependency in core
@@ -197,6 +214,9 @@ module RuboCop
end
end
+ # This cop makes sure that the safe versions of `popen_*` calls are used.
+ #
+ # @api private
class SafePopenCommands < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
test = find_block(body_node, :test)
@@ -225,6 +245,9 @@ module RuboCop
end
end
+ # This cop makes sure that environment variables are passed correctly to `popen_*` calls.
+ #
+ # @api private
class ShellVariables < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
popen_commands = [
@@ -254,6 +277,9 @@ module RuboCop
end
end
+ # This cop makes sure that `license` has the correct format.
+ #
+ # @api private
class LicenseArrays < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
license_node = find_node_method_by_name(body_node, :license)
@@ -272,6 +298,9 @@ module RuboCop
end
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)
license_node = find_node_method_by_name(body_node, :license)
@@ -286,6 +315,9 @@ module RuboCop
end
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)
# FileUtils is included in Formula
@@ -545,6 +577,9 @@ module RuboCop
end
module FormulaAuditStrict
+ # This cop makes sure that no build-time checks are performed.
+ #
+ # @api private
class MakeCheck < FormulaCop
MAKE_CHECK_ALLOWLIST = %w[
beecrypt
@@ -588,6 +623,9 @@ module RuboCop
end
end
+ # This cop makes sure that shell command arguments are separated.
+ #
+ # @api private
class ShellCommands < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
# Match shell commands separated by spaces in the same string
diff --git a/Library/Homebrew/rubocops/shared/desc_helper.rb b/Library/Homebrew/rubocops/shared/desc_helper.rb
index 3ed62a036ba4653b95e06ebe6393f30cfbdee48c..80092a8df7577a3468e6c5dd285145fd56f806c7 100644
--- a/Library/Homebrew/rubocops/shared/desc_helper.rb
+++ b/Library/Homebrew/rubocops/shared/desc_helper.rb
@@ -5,6 +5,8 @@ require "rubocops/shared/helper_functions"
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 a5e893c6ae8a72bc8742ee02170e7777a138a278..8b7388f94ca0bb8db075d13e7398545333bb9ae7 100644
--- a/Library/Homebrew/rubocops/shared/helper_functions.rb
+++ b/Library/Homebrew/rubocops/shared/helper_functions.rb
@@ -2,6 +2,9 @@
module RuboCop
module Cop
+ # Helper functions for cops.
+ #
+ # @api private
module HelperFunctions
include RangeHelp
diff --git a/Library/Homebrew/rubocops/text.rb b/Library/Homebrew/rubocops/text.rb
index 49dece4dd4e878710a85c64587165700be5323ec..b8fa914e4d3c18cb552a9f56de9a2db9d512bd9c 100644
--- a/Library/Homebrew/rubocops/text.rb
+++ b/Library/Homebrew/rubocops/text.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
module RuboCop
module Cop
module FormulaAudit
+ # This cop 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)
@full_source_content = source_buffer(node).source
@@ -122,6 +125,9 @@ module RuboCop
end
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)
find_method_with_args(body_node, :go_resource) do
diff --git a/Library/Homebrew/rubocops/urls.rb b/Library/Homebrew/rubocops/urls.rb
index 8f6a3aefda9a016854634b9c11441bffa3711e97..ca6a22d1ecd3c42497691401ba67a3fe4cb6aca3 100644
--- a/Library/Homebrew/rubocops/urls.rb
+++ b/Library/Homebrew/rubocops/urls.rb
@@ -6,6 +6,8 @@ module RuboCop
module Cop
module FormulaAudit
# This cop audits URLs and mirrors in Formulae.
+ #
+ # @api private
class Urls < FormulaCop
# These are parts of URLs that look like binaries but actually aren't.
NOT_A_BINARY_URL_PREFIX_ALLOWLIST = %w[
@@ -285,6 +287,9 @@ module RuboCop
end
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)
urls = find_every_func_call_by_name(body_node, :url)
diff --git a/Library/Homebrew/rubocops/version.rb b/Library/Homebrew/rubocops/version.rb
index f4ed91c18d5cef84dd5a54094c1b921ec0c9ca37..de47a9d290c4511ff10d6b5ed26fb3f32fae31c4 100644
--- a/Library/Homebrew/rubocops/version.rb
+++ b/Library/Homebrew/rubocops/version.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
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 d50ec020f11a7a6f1c1c5781780b51c6054aa8e8..a0ab6c2141511a0e507986891fecc0693f100c60 100644
--- a/Library/Homebrew/sandbox.rb
+++ b/Library/Homebrew/sandbox.rb
@@ -3,8 +3,12 @@
require "erb"
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
def self.available?
OS.mac? && File.executable?(SANDBOX_EXEC)
@@ -139,6 +143,7 @@ class Sandbox
end
end
+ # Configuration profile for a sandbox.
class SandboxProfile
SEATBELT_ERB = <<~ERB
(version 1)
@@ -181,4 +186,5 @@ class Sandbox
ERB.new(SEATBELT_ERB).result(binding)
end
end
+ private_constant :SandboxProfile
end
diff --git a/Library/Homebrew/search.rb b/Library/Homebrew/search.rb
index 7bfb9edba33bf7e9638635ce9c7345eab5f1537a..29fe98e8c2e7a85621c3c8b3a2412b413536b300 100644
--- a/Library/Homebrew/search.rb
+++ b/Library/Homebrew/search.rb
@@ -4,6 +4,9 @@ require "searchable"
require "description_cache_store"
module Homebrew
+ # Helper module for searching formulae or casks.
+ #
+ # @api private
module Search
def query_regexp(query)
if m = query.match(%r{^/(.*)/$})
diff --git a/Library/Homebrew/searchable.rb b/Library/Homebrew/searchable.rb
index 43fa35241dcd0502c4cb3eefcf18933effe2d738..9b9adc76064688925baff0c20d9cc5f8f969542c 100644
--- a/Library/Homebrew/searchable.rb
+++ b/Library/Homebrew/searchable.rb
@@ -1,5 +1,8 @@
# frozen_string_literal: true
+# Helper module for making a class searchable with both regular expressions and strings.
+#
+# @api private
module Searchable
def search(string_or_regex, &block)
case string_or_regex
diff --git a/Library/Homebrew/style.rb b/Library/Homebrew/style.rb
index be40a4dd41c41d7459d27434e42e5f70ebe7dfc8..36f538b158db27beb34f8479f236063af1fa231d 100644
--- a/Library/Homebrew/style.rb
+++ b/Library/Homebrew/style.rb
@@ -1,6 +1,9 @@
# frozen_string_literal: true
module Homebrew
+ # Helper module for running RuboCop.
+ #
+ # @api private
module Style
module_function
@@ -127,6 +130,7 @@ module Homebrew
rubocop_success && shellcheck_success
end
+ # Result of a RuboCop run.
class RubocopResults
def initialize(json)
@metadata = json["metadata"]
@@ -144,6 +148,7 @@ module Homebrew
end
end
+ # A RuboCop offense.
class RubocopOffense
attr_reader :severity, :message, :corrected, :location, :cop_name
@@ -177,6 +182,7 @@ module Homebrew
end
end
+ # Source location of a RuboCop offense.
class RubocopLineLocation
attr_reader :line, :column, :length
diff --git a/Library/Homebrew/system_command.rb b/Library/Homebrew/system_command.rb
index b507ec1434f9d02e2289b55ee9338b1fb841d5d1..05c4cb86c2f1f0e31dadb02cb7076b332053c9de 100644
--- a/Library/Homebrew/system_command.rb
+++ b/Library/Homebrew/system_command.rb
@@ -9,6 +9,9 @@ require "extend/io"
require "extend/hash_validator"
using HashValidator
+# Make `system_command` available everywhere.
+#
+# @api private
module Kernel
def system_command(*args)
SystemCommand.run(*args)
@@ -19,6 +22,9 @@ module Kernel
end
end
+# Class for running sub-processes and capturing their output and exit status.
+#
+# @api private
class SystemCommand
include Context
extend Predicable
@@ -167,6 +173,7 @@ class SystemCommand
sources.each(&:close_read)
end
+ # Result containing the output and exit status of a finished sub-process.
class Result
include Context
diff --git a/Library/Homebrew/unpack_strategy.rb b/Library/Homebrew/unpack_strategy.rb
index 8d56e405e36220eb1aa2c6832429e416684d2a2a..9540b4029bef58a99e9c302e19450663e059065d 100644
--- a/Library/Homebrew/unpack_strategy.rb
+++ b/Library/Homebrew/unpack_strategy.rb
@@ -1,8 +1,12 @@
# frozen_string_literal: true
+# Module containing all available strategies for unpacking archives.
+#
+# @api private
module UnpackStrategy
+ # Helper module for identifying the file type.
module Magic
- # length of the longest regex (currently Tar)
+ # Length of the longest regex (currently Tar).
MAX_MAGIC_NUMBER_LENGTH = 262
refine Pathname do
@@ -31,18 +35,18 @@ module UnpackStrategy
def self.strategies
@strategies ||= [
- Tar, # needs to be before Bzip2/Gzip/Xz/Lzma
+ Tar, # Needs to be before Bzip2/Gzip/Xz/Lzma.
Pax,
Gzip,
Lzma,
Xz,
Lzip,
- Air, # needs to be before Zip
- Jar, # needs to be before Zip
- LuaRock, # needs to be before Zip
- MicrosoftOfficeXml, # needs to be before Zip
+ Air, # Needs to be before `Zip`.
+ Jar, # Needs to be before `Zip`.
+ LuaRock, # Needs to be before `Zip`.
+ MicrosoftOfficeXml, # Needs to be before `Zip`.
Zip,
- Pkg, # needs to be before Xar
+ Pkg, # Needs to be before `Xar`.
Xar,
Ttf,
Otf,
@@ -50,10 +54,10 @@ module UnpackStrategy
Mercurial,
Subversion,
Cvs,
- SelfExtractingExecutable, # needs to be before Cab
+ SelfExtractingExecutable, # Needs to be before `Cab`.
Cab,
Executable,
- Dmg, # needs to be before Bzip2
+ Dmg, # Needs to be before `Bzip2`.
Bzip2,
Fossil,
Bazaar,
diff --git a/Library/Homebrew/unpack_strategy/air.rb b/Library/Homebrew/unpack_strategy/air.rb
index 480a5281dea2f5487cb93c685f8038d85c123efa..47a2a7f6b9026851c766e3e8e37f71197558b510 100644
--- a/Library/Homebrew/unpack_strategy/air.rb
+++ b/Library/Homebrew/unpack_strategy/air.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking Adobe Air archives.
class Air
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/bazaar.rb b/Library/Homebrew/unpack_strategy/bazaar.rb
index fd3d1bd7a1c536b57a14b2bbd0584eb9f578a02f..3bb3c4d6b10fa3fb65cdf978edf82fafa683bad3 100644
--- a/Library/Homebrew/unpack_strategy/bazaar.rb
+++ b/Library/Homebrew/unpack_strategy/bazaar.rb
@@ -3,6 +3,7 @@
require_relative "directory"
module UnpackStrategy
+ # Strategy for unpacking Bazaar archives.
class Bazaar < Directory
using Magic
diff --git a/Library/Homebrew/unpack_strategy/bzip2.rb b/Library/Homebrew/unpack_strategy/bzip2.rb
index fd9592d78fc6300d17d00b2661141070140c7a87..9eff311a837656bb4c2c115eeb96ea575c530ee7 100644
--- a/Library/Homebrew/unpack_strategy/bzip2.rb
+++ b/Library/Homebrew/unpack_strategy/bzip2.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking bzip2 archives.
class Bzip2
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/cab.rb b/Library/Homebrew/unpack_strategy/cab.rb
index 9de498ce036887e101b42cb5d7fc9f3c28885d35..f36fa1f580e808ddb4c2d781eb67179d516c946e 100644
--- a/Library/Homebrew/unpack_strategy/cab.rb
+++ b/Library/Homebrew/unpack_strategy/cab.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking Cabinet archives.
class Cab
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/compress.rb b/Library/Homebrew/unpack_strategy/compress.rb
index cf9101f726533c514a1ad474eb69f09fc7cb0f16..668272df85fba733083e31530b78d5fea1d313c7 100644
--- a/Library/Homebrew/unpack_strategy/compress.rb
+++ b/Library/Homebrew/unpack_strategy/compress.rb
@@ -3,6 +3,7 @@
require_relative "tar"
module UnpackStrategy
+ # Strategy for unpacking compress archives.
class Compress < Tar
using Magic
diff --git a/Library/Homebrew/unpack_strategy/cvs.rb b/Library/Homebrew/unpack_strategy/cvs.rb
index 7991c674cd73b4e2c529ba176551d84a8ac3a24d..36e4d506e4b192f61c19286a72d57549ec470c0a 100644
--- a/Library/Homebrew/unpack_strategy/cvs.rb
+++ b/Library/Homebrew/unpack_strategy/cvs.rb
@@ -3,6 +3,7 @@
require_relative "directory"
module UnpackStrategy
+ # Strategy for unpacking CVS repositories.
class Cvs < Directory
using Magic
diff --git a/Library/Homebrew/unpack_strategy/directory.rb b/Library/Homebrew/unpack_strategy/directory.rb
index d7493398353bbe0795a40a982163b56097c3cad5..06d8dd98884ec0fc448c3489a772e2681955c2fa 100644
--- a/Library/Homebrew/unpack_strategy/directory.rb
+++ b/Library/Homebrew/unpack_strategy/directory.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking directories.
class Directory
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/dmg.rb b/Library/Homebrew/unpack_strategy/dmg.rb
index f6d34c42058a0ab651999190be3b388da5fcfff1..b263d56e87f796bc58a16d2658ece4df91ace3a6 100644
--- a/Library/Homebrew/unpack_strategy/dmg.rb
+++ b/Library/Homebrew/unpack_strategy/dmg.rb
@@ -3,9 +3,11 @@
require "tempfile"
module UnpackStrategy
+ # Strategy for unpacking disk images.
class Dmg
include UnpackStrategy
+ # Helper module for listing the contents of a volume mounted from a disk image.
module Bom
DMG_METADATA = Set.new(%w[
.background
@@ -23,11 +25,12 @@ module UnpackStrategy
private_constant :DMG_METADATA
refine Pathname do
+ # Check if path is considered disk image metadata.
def dmg_metadata?
DMG_METADATA.include?(cleanpath.ascend.to_a.last.to_s)
end
- # symlinks to system directories (commonly to /Applications)
+ # Check if path is a symlink to a system directory (commonly to /Applications).
def system_dir_symlink?
symlink? && MacOS.system_dir?(dirname.join(readlink))
end
@@ -48,9 +51,9 @@ module UnpackStrategy
end
private_constant :Bom
- using Bom
-
+ # Strategy for unpacking a volume mounted from a disk image.
class Mount
+ using Bom
include UnpackStrategy
def eject(verbose: false)
diff --git a/Library/Homebrew/unpack_strategy/executable.rb b/Library/Homebrew/unpack_strategy/executable.rb
index 82a84e1448edda80310010fa901978430da91242..57e99908f01b612794ff14768cb37d7879eb0425 100644
--- a/Library/Homebrew/unpack_strategy/executable.rb
+++ b/Library/Homebrew/unpack_strategy/executable.rb
@@ -3,6 +3,7 @@
require_relative "uncompressed"
module UnpackStrategy
+ # Strategy for unpacking executables.
class Executable < Uncompressed
using Magic
diff --git a/Library/Homebrew/unpack_strategy/fossil.rb b/Library/Homebrew/unpack_strategy/fossil.rb
index 6b7a5d931059e72df60be31a3782c5f7ffbd5d6f..ea7f2216b84e24296c29c9610cdd4bcb2b883e59 100644
--- a/Library/Homebrew/unpack_strategy/fossil.rb
+++ b/Library/Homebrew/unpack_strategy/fossil.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking Fossil repositories.
class Fossil
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/generic_unar.rb b/Library/Homebrew/unpack_strategy/generic_unar.rb
index 347dd6ac1967a48ac5c24be16722928e76f73549..5458141748c25ca74c30a6b76803029548126be6 100644
--- a/Library/Homebrew/unpack_strategy/generic_unar.rb
+++ b/Library/Homebrew/unpack_strategy/generic_unar.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking archives with `unar`.
class GenericUnar
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/git.rb b/Library/Homebrew/unpack_strategy/git.rb
index 4aefb640d3c529c3efcf5c19866c00c48b542441..c704f13a47e8b7e5ae804f365ffbf4fabeb380b2 100644
--- a/Library/Homebrew/unpack_strategy/git.rb
+++ b/Library/Homebrew/unpack_strategy/git.rb
@@ -3,6 +3,7 @@
require_relative "directory"
module UnpackStrategy
+ # Strategy for unpacking Git repositories.
class Git < Directory
using Magic
diff --git a/Library/Homebrew/unpack_strategy/gzip.rb b/Library/Homebrew/unpack_strategy/gzip.rb
index 5db11be7247057afb860ea02e59e4c5d39247fb8..8f576788d59f50b915c73e202347d2c6bbde1a4c 100644
--- a/Library/Homebrew/unpack_strategy/gzip.rb
+++ b/Library/Homebrew/unpack_strategy/gzip.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking gzip archives.
class Gzip
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/jar.rb b/Library/Homebrew/unpack_strategy/jar.rb
index 9827cc62c11e1dbd1b07438d00016c5fcf528562..8fc3a70476c2e52a44af799577f3129c63d3b596 100644
--- a/Library/Homebrew/unpack_strategy/jar.rb
+++ b/Library/Homebrew/unpack_strategy/jar.rb
@@ -3,6 +3,7 @@
require_relative "uncompressed"
module UnpackStrategy
+ # Strategy for unpacking Java archives.
class Jar < Uncompressed
using Magic
diff --git a/Library/Homebrew/unpack_strategy/lha.rb b/Library/Homebrew/unpack_strategy/lha.rb
index 0527013208a6dfa4fe051b695b4c5f65bcfa158e..d3bfcaf87e0f3c31226ccf271c5880fdbc44e8e1 100644
--- a/Library/Homebrew/unpack_strategy/lha.rb
+++ b/Library/Homebrew/unpack_strategy/lha.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking LHa archives.
class Lha
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/lua_rock.rb b/Library/Homebrew/unpack_strategy/lua_rock.rb
index 70759c981ef1ba4e1aa03822e67f6c188c00e7a4..8517b140e5a230b51e38becb395d386175e927c8 100644
--- a/Library/Homebrew/unpack_strategy/lua_rock.rb
+++ b/Library/Homebrew/unpack_strategy/lua_rock.rb
@@ -3,6 +3,7 @@
require_relative "uncompressed"
module UnpackStrategy
+ # Strategy for unpacking LuaRock archives.
class LuaRock < Uncompressed
using Magic
diff --git a/Library/Homebrew/unpack_strategy/lzip.rb b/Library/Homebrew/unpack_strategy/lzip.rb
index 121dea7a77e3397d4f17ce209e2a9bc1379a38ec..687917cea4bb727fd18b1ab7dc42d49af0d30a7f 100644
--- a/Library/Homebrew/unpack_strategy/lzip.rb
+++ b/Library/Homebrew/unpack_strategy/lzip.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking lzip archives.
class Lzip
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/lzma.rb b/Library/Homebrew/unpack_strategy/lzma.rb
index 257fb7598485bdf0f8453da1ee08117f4518d09a..006fcfb7414ee5ee2fb21fb82b58e6497a1dc3ba 100644
--- a/Library/Homebrew/unpack_strategy/lzma.rb
+++ b/Library/Homebrew/unpack_strategy/lzma.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking LZMA archives.
class Lzma
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/mercurial.rb b/Library/Homebrew/unpack_strategy/mercurial.rb
index 4799a5e0c1e6d585115c7f965a965e81a1bfa59c..7e0d3b64d28daece67bdcba86dfae3292a4fd954 100644
--- a/Library/Homebrew/unpack_strategy/mercurial.rb
+++ b/Library/Homebrew/unpack_strategy/mercurial.rb
@@ -3,6 +3,7 @@
require_relative "directory"
module UnpackStrategy
+ # Strategy for unpacking Mercurial repositories.
class Mercurial < Directory
using Magic
diff --git a/Library/Homebrew/unpack_strategy/microsoft_office_xml.rb b/Library/Homebrew/unpack_strategy/microsoft_office_xml.rb
index 869c0debbd2ddc426555437f192767ec3118f3c9..8c3463be0840f946d4f1b32ee7b1b0e6c27ce53a 100644
--- a/Library/Homebrew/unpack_strategy/microsoft_office_xml.rb
+++ b/Library/Homebrew/unpack_strategy/microsoft_office_xml.rb
@@ -3,6 +3,7 @@
require_relative "uncompressed"
module UnpackStrategy
+ # Strategy for unpacking Microsoft Office documents.
class MicrosoftOfficeXml < Uncompressed
using Magic
diff --git a/Library/Homebrew/unpack_strategy/otf.rb b/Library/Homebrew/unpack_strategy/otf.rb
index ff4c20662b94c015c75457694f79a72482907891..17b55ed7a653b170c83a40723065ca3b7185e942 100644
--- a/Library/Homebrew/unpack_strategy/otf.rb
+++ b/Library/Homebrew/unpack_strategy/otf.rb
@@ -3,6 +3,7 @@
require_relative "uncompressed"
module UnpackStrategy
+ # Strategy for unpacking OpenType fonts.
class Otf < Uncompressed
using Magic
diff --git a/Library/Homebrew/unpack_strategy/p7zip.rb b/Library/Homebrew/unpack_strategy/p7zip.rb
index 6110a275bcdfd8027652f16a88e6697d6716092e..df779331912c14fd388267addeb3c12bd3787f47 100644
--- a/Library/Homebrew/unpack_strategy/p7zip.rb
+++ b/Library/Homebrew/unpack_strategy/p7zip.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking P7ZIP archives.
class P7Zip
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/pax.rb b/Library/Homebrew/unpack_strategy/pax.rb
index bd1fe0d1e7f493460bbb88ebd10c31238109bae2..89138e57798b9b3d9405589c7d0ac68aa622814f 100644
--- a/Library/Homebrew/unpack_strategy/pax.rb
+++ b/Library/Homebrew/unpack_strategy/pax.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking pax archives.
class Pax
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/pkg.rb b/Library/Homebrew/unpack_strategy/pkg.rb
index 10ae0402412cf4eb3f162432962030811ae838db..8dad4a44362293413458192fd792fefa8d92f9a8 100644
--- a/Library/Homebrew/unpack_strategy/pkg.rb
+++ b/Library/Homebrew/unpack_strategy/pkg.rb
@@ -3,6 +3,7 @@
require_relative "uncompressed"
module UnpackStrategy
+ # Strategy for unpacking macOS package installers.
class Pkg < Uncompressed
using Magic
diff --git a/Library/Homebrew/unpack_strategy/rar.rb b/Library/Homebrew/unpack_strategy/rar.rb
index 64604792a8756508045fb215214edd08023ee306..5863b0742285f5c587d7fe1db6e6465dd7de7c80 100644
--- a/Library/Homebrew/unpack_strategy/rar.rb
+++ b/Library/Homebrew/unpack_strategy/rar.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking RAR archives.
class Rar
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/self_extracting_executable.rb b/Library/Homebrew/unpack_strategy/self_extracting_executable.rb
index 298070fde3bdc58fe03e21074126e76bcf86327c..9de9120b023de4d788242275568c10b122d2f2e3 100644
--- a/Library/Homebrew/unpack_strategy/self_extracting_executable.rb
+++ b/Library/Homebrew/unpack_strategy/self_extracting_executable.rb
@@ -3,6 +3,7 @@
require_relative "generic_unar"
module UnpackStrategy
+ # Strategy for unpacking self-extracting executables.
class SelfExtractingExecutable < GenericUnar
using Magic
diff --git a/Library/Homebrew/unpack_strategy/sit.rb b/Library/Homebrew/unpack_strategy/sit.rb
index 9f537d64e80c33432eb79beb53f8ee6273aeef64..5ec16b48ab32035e230220f5d5047aac7834f226 100644
--- a/Library/Homebrew/unpack_strategy/sit.rb
+++ b/Library/Homebrew/unpack_strategy/sit.rb
@@ -3,6 +3,7 @@
require_relative "generic_unar"
module UnpackStrategy
+ # Strategy for unpacking Stuffit archives.
class Sit < GenericUnar
using Magic
diff --git a/Library/Homebrew/unpack_strategy/subversion.rb b/Library/Homebrew/unpack_strategy/subversion.rb
index c9dbfdc644e626b2e14a9e18c9815068501dcfbf..0c90b36605a72322c3fbcb3f73ca29e88386f939 100644
--- a/Library/Homebrew/unpack_strategy/subversion.rb
+++ b/Library/Homebrew/unpack_strategy/subversion.rb
@@ -3,6 +3,7 @@
require_relative "directory"
module UnpackStrategy
+ # Strategy for unpacking Subversion repositories.
class Subversion < Directory
using Magic
diff --git a/Library/Homebrew/unpack_strategy/tar.rb b/Library/Homebrew/unpack_strategy/tar.rb
index 17be99f4069909f8fa0c45641cfe38aa1f373e02..25c30973dd89f9d475c1972ce21d6ac22f42bd53 100644
--- a/Library/Homebrew/unpack_strategy/tar.rb
+++ b/Library/Homebrew/unpack_strategy/tar.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking tar archives.
class Tar
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/ttf.rb b/Library/Homebrew/unpack_strategy/ttf.rb
index c3107d6594c869f1e19b7455e5fd7c46f93d2fcf..54c6a6bd8273fae70b5edee8b013b584b97ce972 100644
--- a/Library/Homebrew/unpack_strategy/ttf.rb
+++ b/Library/Homebrew/unpack_strategy/ttf.rb
@@ -3,6 +3,7 @@
require_relative "uncompressed"
module UnpackStrategy
+ # Strategy for unpacking TrueType fonts.
class Ttf < Uncompressed
using Magic
diff --git a/Library/Homebrew/unpack_strategy/uncompressed.rb b/Library/Homebrew/unpack_strategy/uncompressed.rb
index be11b25c26b1d6ea320dc52309b8e73fe0aa4455..ea7f943a204519d396bd72e5bcf138d76c93b374 100644
--- a/Library/Homebrew/unpack_strategy/uncompressed.rb
+++ b/Library/Homebrew/unpack_strategy/uncompressed.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking uncompressed files.
class Uncompressed
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/xar.rb b/Library/Homebrew/unpack_strategy/xar.rb
index 29d0e71783af2220e96963cc6c75692285499d4d..69422eb66005396601f2dc9dcdda31c3e97f104b 100644
--- a/Library/Homebrew/unpack_strategy/xar.rb
+++ b/Library/Homebrew/unpack_strategy/xar.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking xar archives.
class Xar
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/xz.rb b/Library/Homebrew/unpack_strategy/xz.rb
index a0ce3fbc167adcec0b1d2cd7f72b991bc133b4ea..29ac0c182d8831717a662b06e8ba5a486e51e6a5 100644
--- a/Library/Homebrew/unpack_strategy/xz.rb
+++ b/Library/Homebrew/unpack_strategy/xz.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking xz archives.
class Xz
include UnpackStrategy
diff --git a/Library/Homebrew/unpack_strategy/zip.rb b/Library/Homebrew/unpack_strategy/zip.rb
index 80eee7288608d2b02f5d0679be240913e64d1796..e58e556c7c68ce737f5f9bf151a3e01b029f44a3 100644
--- a/Library/Homebrew/unpack_strategy/zip.rb
+++ b/Library/Homebrew/unpack_strategy/zip.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
module UnpackStrategy
+ # Strategy for unpacking ZIP archives.
class Zip
include UnpackStrategy
diff --git a/Library/Homebrew/utils/analytics.rb b/Library/Homebrew/utils/analytics.rb
index 8f0e7e0e4d6bc555146c93b1fdcdab63a54dea16..9f0ce48c7cac231499dcc81f6ddcc2ba5307b580 100644
--- a/Library/Homebrew/utils/analytics.rb
+++ b/Library/Homebrew/utils/analytics.rb
@@ -3,6 +3,9 @@
require "erb"
module Utils
+ # Helper module for fetching and reporting analytics data.
+ #
+ # @api private
module Analytics
class << self
include Context
diff --git a/Library/Homebrew/utils/formatter.rb b/Library/Homebrew/utils/formatter.rb
index 61cdc06b87acee03ef2834459e57d7dd0a554ac4..60e88c60e1c6353dc8976a9d7e86a6dbe49586d2 100644
--- a/Library/Homebrew/utils/formatter.rb
+++ b/Library/Homebrew/utils/formatter.rb
@@ -2,6 +2,9 @@
require "utils/tty"
+# Helper module for formatting output.
+#
+# @api private
module Formatter
module_function
diff --git a/Library/Homebrew/utils/github.rb b/Library/Homebrew/utils/github.rb
index c04289fcbe5a7b8b7124ecff426e0ae7b0f05b1e..afb40bac3eccd89562bf81db1f5913503b071c60 100644
--- a/Library/Homebrew/utils/github.rb
+++ b/Library/Homebrew/utils/github.rb
@@ -3,6 +3,9 @@
require "tempfile"
require "uri"
+# Helper functions for interacting with the GitHub API.
+#
+# @api private
module GitHub
module_function
@@ -15,10 +18,12 @@ module GitHub
"https://github.com/settings/tokens/new?scopes=#{ALL_SCOPES.join(",")}&description=Homebrew",
).freeze
+ # Generic API error.
class Error < RuntimeError
attr_reader :github_message
end
+ # Error when the requested URL is not found.
class HTTPNotFoundError < Error
def initialize(github_message)
@github_message = github_message
@@ -26,6 +31,7 @@ module GitHub
end
end
+ # Error when the API rate limit is exceeded.
class RateLimitExceededError < Error
def initialize(reset, github_message)
@github_message = github_message
@@ -42,6 +48,7 @@ module GitHub
end
end
+ # Error when authentication fails.
class AuthenticationFailedError < Error
def initialize(github_message)
@github_message = github_message
@@ -65,6 +72,7 @@ module GitHub
end
end
+ # Error when the API returns a validation error.
class ValidationFailedError < Error
def initialize(github_message, errors)
@github_message = if errors.empty?
diff --git a/Library/Homebrew/utils/link.rb b/Library/Homebrew/utils/link.rb
index 7c24b13b1dd95142e27560ff3a217cfd88e01c47..8b3c6bb37e96bb796117422aabc290253749421d 100644
--- a/Library/Homebrew/utils/link.rb
+++ b/Library/Homebrew/utils/link.rb
@@ -1,6 +1,9 @@
# frozen_string_literal: true
module Utils
+ # Helper functions for creating symlinks.
+ #
+ # @api private
module Link
module_function
diff --git a/Library/Homebrew/utils/tty.rb b/Library/Homebrew/utils/tty.rb
index 4e7044c8577dfeb7f7ee15653717627e6dc445a0..a09f2f375b69ab6b6554ef7c3d0766024503fe68 100644
--- a/Library/Homebrew/utils/tty.rb
+++ b/Library/Homebrew/utils/tty.rb
@@ -1,5 +1,8 @@
# frozen_string_literal: true
+# Various helper functions for interacting with TTYs.
+#
+# @api private
module Tty
module_function
diff --git a/Library/Homebrew/utils/user.rb b/Library/Homebrew/utils/user.rb
index ce3e8e6b2e42444f8b4ec73b687551785a3afcd3..0d5b94fb346c14d4debcc141265d77e4dbb5200e 100644
--- a/Library/Homebrew/utils/user.rb
+++ b/Library/Homebrew/utils/user.rb
@@ -5,7 +5,11 @@ require "etc"
require "system_command"
+# A system user.
+#
+# @api private
class User < DelegateClass(String)
+ # Return whether the user has an active GUI session.
def gui?
out, _, status = system_command "who"
return false unless status.success?
@@ -15,6 +19,7 @@ class User < DelegateClass(String)
.any? { |user, type,| user == self && type == "console" }
end
+ # Return the current user.
def self.current
return @current if defined?(@current)