Merge pull request #8339 from reitermarkus/documentation

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

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

 # 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