Merge pull request #8339 from reitermarkus/documentation

Improve documentation and add `@api private` to internal classes.

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

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:

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'

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

Library/Homebrew/bintray.rb

@@ -3,6 +3,9 @@
 require "utils/curl"
 require "json"
 
+# Bintray API client.
+#
+# @api private
 class Bintray
   include Context
 

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
 

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)

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

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

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

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,

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

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"

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

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)

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

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

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

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

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}'"

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

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
 

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"

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"

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
 

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

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

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"

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"

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

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

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

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]

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"

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"

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 }

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

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

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)

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
 

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
 

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
 

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

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

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
 

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."

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

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
 

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, "_")

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

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

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

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

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

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

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

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."

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

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

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

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
       #

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."

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."

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>."

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."

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

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."

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

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",

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

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
 

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,

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
 

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
 

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)

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,

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,

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,

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
 

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

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

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

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,

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."

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

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)

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"

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|

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"

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)

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
 

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
 

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?

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
 

Library/Homebrew/caveats.rb

@@ -2,6 +2,9 @@
 
 require "language/python"
 
+# A formula's caveats.
+#
+# @api private
 class Caveats
   extend Forwardable
 

Library/Homebrew/checksum.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# A formula's checksum.
+#
+# @api private
 class Checksum
   extend Forwardable
 

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

Library/Homebrew/commands.rb

@@ -2,6 +2,9 @@
 
 require "cask/cmd"
 
+# Helper functions for commands.
+#
+# @api private
 module Commands
   module_function
 

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
 

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