From 8fc4ac0ad724f89168d97c348542041805cfa544 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 10:34:07 +0200
Subject: [PATCH] Document `Cask::Cmd`.

---
 Library/Homebrew/cask/cmd.rb                           | 7 +++++++
 Library/Homebrew/cask/cmd/--cache.rb                   | 3 +++
 Library/Homebrew/cask/cmd/abstract_command.rb          | 3 +++
 Library/Homebrew/cask/cmd/abstract_internal_command.rb | 3 +++
 Library/Homebrew/cask/cmd/audit.rb                     | 3 +++
 Library/Homebrew/cask/cmd/cat.rb                       | 3 +++
 Library/Homebrew/cask/cmd/create.rb                    | 3 +++
 Library/Homebrew/cask/cmd/doctor.rb                    | 3 +++
 Library/Homebrew/cask/cmd/edit.rb                      | 3 +++
 Library/Homebrew/cask/cmd/fetch.rb                     | 3 +++
 Library/Homebrew/cask/cmd/help.rb                      | 3 +++
 Library/Homebrew/cask/cmd/home.rb                      | 3 +++
 Library/Homebrew/cask/cmd/info.rb                      | 3 +++
 Library/Homebrew/cask/cmd/install.rb                   | 3 +++
 Library/Homebrew/cask/cmd/internal_help.rb             | 3 +++
 Library/Homebrew/cask/cmd/internal_stanza.rb           | 3 +++
 Library/Homebrew/cask/cmd/list.rb                      | 3 +++
 Library/Homebrew/cask/cmd/outdated.rb                  | 3 +++
 Library/Homebrew/cask/cmd/reinstall.rb                 | 3 +++
 Library/Homebrew/cask/cmd/style.rb                     | 3 +++
 Library/Homebrew/cask/cmd/uninstall.rb                 | 3 +++
 Library/Homebrew/cask/cmd/upgrade.rb                   | 3 +++
 Library/Homebrew/cask/cmd/zap.rb                       | 3 +++
 23 files changed, 73 insertions(+)

diff --git a/Library/Homebrew/cask/cmd.rb b/Library/Homebrew/cask/cmd.rb
index 674f4f452e..b353a79fc6 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 310c79d84e..81d3acc7de 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 2b768e69c2..c19cb18726 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 61cfec4fe2..b15b9acc90 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 ee457e9f76..6bf08325a4 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 a75158ae30..3d731b1d6c 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 099b5fd737..c190161fa6 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 c052483445..dafc4e5774 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 94798b786f..bbeffbf730 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 141ae73e76..e42208a31b 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 bef0e9b0ce..fee20683db 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 22a32486ec..291256519a 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 a52a40464b..9667f2bfc2 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 55b8f77ee8..93d03d1fb2 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 878a07bad8..edd33fc2df 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 41f91ebf5c..c392d508a3 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 87098cf917..55f6e937cd 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 43675d5a10..c84a1358a4 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 2264b246be..6303a10353 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 b24b1b5c20..7db1ac6b57 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 affb7cc723..c02d68cf63 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 2562cdfab0..7f56f805c0 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 2168588e77..9b208899ab 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