Document cask exceptions.

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