From b582efceaa5dffec20db95c0e83d2d85466ae2fc Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:31:55 +0200
Subject: [PATCH] Document cask exceptions.

---
 Library/Homebrew/cask/exceptions.rb | 66 +++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/Library/Homebrew/cask/exceptions.rb b/Library/Homebrew/cask/exceptions.rb
index 9614b6780e..7a97f7f133 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."