From d8eb508500936a1ef0734ff78d84fb58f6e36c91 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Sun, 9 Aug 2020 02:59:35 +0200
Subject: [PATCH 001/111] Document `Tty`.

---
 Library/Homebrew/utils/tty.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/utils/tty.rb b/Library/Homebrew/utils/tty.rb
index 4e7044c857..a09f2f375b 100644
--- a/Library/Homebrew/utils/tty.rb
+++ b/Library/Homebrew/utils/tty.rb
@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Various helper functions for interacting with TTYs.
+#
+# @api private
 module Tty
   module_function
 

From 319a2881985fa62c1b67f0f64dcec55ddaa1b62a Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Sun, 9 Aug 2020 03:00:13 +0200
Subject: [PATCH 002/111] Document `User`.

---
 Library/Homebrew/utils/user.rb | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Library/Homebrew/utils/user.rb b/Library/Homebrew/utils/user.rb
index ce3e8e6b2e..0d5b94fb34 100644
--- a/Library/Homebrew/utils/user.rb
+++ b/Library/Homebrew/utils/user.rb
@@ -5,7 +5,11 @@ require "etc"
 
 require "system_command"
 
+# A system user.
+#
+# @api private
 class User < DelegateClass(String)
+  # Return whether the user has an active GUI session.
   def gui?
     out, _, status = system_command "who"
     return false unless status.success?
@@ -15,6 +19,7 @@ class User < DelegateClass(String)
        .any? { |user, type,| user == self && type == "console" }
   end
 
+  # Return the current user.
   def self.current
     return @current if defined?(@current)
 

From 62c2ee332f3b37541682f39dd200997ce376a417 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Sun, 9 Aug 2020 03:14:44 +0200
Subject: [PATCH 003/111] Document `LazyObject`.

---
 Library/Homebrew/lazy_object.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/lazy_object.rb b/Library/Homebrew/lazy_object.rb
index d54f15ed7e..8ea44995eb 100644
--- a/Library/Homebrew/lazy_object.rb
+++ b/Library/Homebrew/lazy_object.rb
@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# An object which lazily evaluates its inner block only once a method is called on it.
+#
+# @api private
 class LazyObject < Delegator
   def initialize(&callable)
     super(callable)

From b7e96e6096589de8d77ce7e38c4fb69311254ee2 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Sun, 9 Aug 2020 03:16:22 +0200
Subject: [PATCH 004/111] Document `LockFile`.

---
 Library/Homebrew/lock_file.rb | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Library/Homebrew/lock_file.rb b/Library/Homebrew/lock_file.rb
index 99c1afda5e..88f017a170 100644
--- a/Library/Homebrew/lock_file.rb
+++ b/Library/Homebrew/lock_file.rb
@@ -2,6 +2,9 @@
 
 require "fcntl"
 
+# A lock file.
+#
+# @api private
 class LockFile
   attr_reader :path
 
@@ -43,12 +46,18 @@ class LockFile
   end
 end
 
+# A lock file for a formula.
+#
+# @api private
 class FormulaLock < LockFile
   def initialize(name)
     super("#{name}.formula")
   end
 end
 
+# A lock file for a cask.
+#
+# @api private
 class CaskLock < LockFile
   def initialize(name)
     super("#{name}.cask")

From 0e7f18a51eb27e880a417c992a6954f929136f72 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Sun, 9 Aug 2020 06:09:05 +0200
Subject: [PATCH 005/111] Document `UnpackStrategy`.

---
 Library/Homebrew/unpack_strategy.rb           | 22 +++++++++++--------
 Library/Homebrew/unpack_strategy/air.rb       |  1 +
 Library/Homebrew/unpack_strategy/bazaar.rb    |  1 +
 Library/Homebrew/unpack_strategy/bzip2.rb     |  1 +
 Library/Homebrew/unpack_strategy/cab.rb       |  1 +
 Library/Homebrew/unpack_strategy/compress.rb  |  1 +
 Library/Homebrew/unpack_strategy/cvs.rb       |  1 +
 Library/Homebrew/unpack_strategy/directory.rb |  1 +
 Library/Homebrew/unpack_strategy/dmg.rb       |  9 +++++---
 .../Homebrew/unpack_strategy/executable.rb    |  1 +
 Library/Homebrew/unpack_strategy/fossil.rb    |  1 +
 .../Homebrew/unpack_strategy/generic_unar.rb  |  1 +
 Library/Homebrew/unpack_strategy/git.rb       |  1 +
 Library/Homebrew/unpack_strategy/gzip.rb      |  1 +
 Library/Homebrew/unpack_strategy/jar.rb       |  1 +
 Library/Homebrew/unpack_strategy/lha.rb       |  1 +
 Library/Homebrew/unpack_strategy/lua_rock.rb  |  1 +
 Library/Homebrew/unpack_strategy/lzip.rb      |  1 +
 Library/Homebrew/unpack_strategy/lzma.rb      |  1 +
 Library/Homebrew/unpack_strategy/mercurial.rb |  1 +
 .../unpack_strategy/microsoft_office_xml.rb   |  1 +
 Library/Homebrew/unpack_strategy/otf.rb       |  1 +
 Library/Homebrew/unpack_strategy/p7zip.rb     |  1 +
 Library/Homebrew/unpack_strategy/pax.rb       |  1 +
 Library/Homebrew/unpack_strategy/pkg.rb       |  1 +
 Library/Homebrew/unpack_strategy/rar.rb       |  1 +
 .../self_extracting_executable.rb             |  1 +
 Library/Homebrew/unpack_strategy/sit.rb       |  1 +
 .../Homebrew/unpack_strategy/subversion.rb    |  1 +
 Library/Homebrew/unpack_strategy/tar.rb       |  1 +
 Library/Homebrew/unpack_strategy/ttf.rb       |  1 +
 .../Homebrew/unpack_strategy/uncompressed.rb  |  1 +
 Library/Homebrew/unpack_strategy/xar.rb       |  1 +
 Library/Homebrew/unpack_strategy/xz.rb        |  1 +
 Library/Homebrew/unpack_strategy/zip.rb       |  1 +
 35 files changed, 52 insertions(+), 12 deletions(-)

diff --git a/Library/Homebrew/unpack_strategy.rb b/Library/Homebrew/unpack_strategy.rb
index 8d56e405e3..9540b4029b 100644
--- a/Library/Homebrew/unpack_strategy.rb
+++ b/Library/Homebrew/unpack_strategy.rb
@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+# Module containing all available strategies for unpacking archives.
+#
+# @api private
 module UnpackStrategy
+  # Helper module for identifying the file type.
   module Magic
-    # length of the longest regex (currently Tar)
+    # Length of the longest regex (currently Tar).
     MAX_MAGIC_NUMBER_LENGTH = 262
 
     refine Pathname do
@@ -31,18 +35,18 @@ module UnpackStrategy
 
   def self.strategies
     @strategies ||= [
-      Tar, # needs to be before Bzip2/Gzip/Xz/Lzma
+      Tar, # Needs to be before Bzip2/Gzip/Xz/Lzma.
       Pax,
       Gzip,
       Lzma,
       Xz,
       Lzip,
-      Air, # needs to be before Zip
-      Jar, # needs to be before Zip
-      LuaRock, # needs to be before Zip
-      MicrosoftOfficeXml, # needs to be before Zip
+      Air, # Needs to be before `Zip`.
+      Jar, # Needs to be before `Zip`.
+      LuaRock, # Needs to be before `Zip`.
+      MicrosoftOfficeXml, # Needs to be before `Zip`.
       Zip,
-      Pkg, # needs to be before Xar
+      Pkg, # Needs to be before `Xar`.
       Xar,
       Ttf,
       Otf,
@@ -50,10 +54,10 @@ module UnpackStrategy
       Mercurial,
       Subversion,
       Cvs,
-      SelfExtractingExecutable, # needs to be before Cab
+      SelfExtractingExecutable, # Needs to be before `Cab`.
       Cab,
       Executable,
-      Dmg, # needs to be before Bzip2
+      Dmg, # Needs to be before `Bzip2`.
       Bzip2,
       Fossil,
       Bazaar,
diff --git a/Library/Homebrew/unpack_strategy/air.rb b/Library/Homebrew/unpack_strategy/air.rb
index 480a5281de..47a2a7f6b9 100644
--- a/Library/Homebrew/unpack_strategy/air.rb
+++ b/Library/Homebrew/unpack_strategy/air.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking Adobe Air archives.
   class Air
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/bazaar.rb b/Library/Homebrew/unpack_strategy/bazaar.rb
index fd3d1bd7a1..3bb3c4d6b1 100644
--- a/Library/Homebrew/unpack_strategy/bazaar.rb
+++ b/Library/Homebrew/unpack_strategy/bazaar.rb
@@ -3,6 +3,7 @@
 require_relative "directory"
 
 module UnpackStrategy
+  # Strategy for unpacking Bazaar archives.
   class Bazaar < Directory
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/bzip2.rb b/Library/Homebrew/unpack_strategy/bzip2.rb
index fd9592d78f..9eff311a83 100644
--- a/Library/Homebrew/unpack_strategy/bzip2.rb
+++ b/Library/Homebrew/unpack_strategy/bzip2.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking bzip2 archives.
   class Bzip2
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/cab.rb b/Library/Homebrew/unpack_strategy/cab.rb
index 9de498ce03..f36fa1f580 100644
--- a/Library/Homebrew/unpack_strategy/cab.rb
+++ b/Library/Homebrew/unpack_strategy/cab.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking Cabinet archives.
   class Cab
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/compress.rb b/Library/Homebrew/unpack_strategy/compress.rb
index cf9101f726..668272df85 100644
--- a/Library/Homebrew/unpack_strategy/compress.rb
+++ b/Library/Homebrew/unpack_strategy/compress.rb
@@ -3,6 +3,7 @@
 require_relative "tar"
 
 module UnpackStrategy
+  # Strategy for unpacking compress archives.
   class Compress < Tar
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/cvs.rb b/Library/Homebrew/unpack_strategy/cvs.rb
index 7991c674cd..36e4d506e4 100644
--- a/Library/Homebrew/unpack_strategy/cvs.rb
+++ b/Library/Homebrew/unpack_strategy/cvs.rb
@@ -3,6 +3,7 @@
 require_relative "directory"
 
 module UnpackStrategy
+  # Strategy for unpacking CVS repositories.
   class Cvs < Directory
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/directory.rb b/Library/Homebrew/unpack_strategy/directory.rb
index d749339835..06d8dd9888 100644
--- a/Library/Homebrew/unpack_strategy/directory.rb
+++ b/Library/Homebrew/unpack_strategy/directory.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking directories.
   class Directory
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/dmg.rb b/Library/Homebrew/unpack_strategy/dmg.rb
index f6d34c4205..b263d56e87 100644
--- a/Library/Homebrew/unpack_strategy/dmg.rb
+++ b/Library/Homebrew/unpack_strategy/dmg.rb
@@ -3,9 +3,11 @@
 require "tempfile"
 
 module UnpackStrategy
+  # Strategy for unpacking disk images.
   class Dmg
     include UnpackStrategy
 
+    # Helper module for listing the contents of a volume mounted from a disk image.
     module Bom
       DMG_METADATA = Set.new(%w[
                                .background
@@ -23,11 +25,12 @@ module UnpackStrategy
       private_constant :DMG_METADATA
 
       refine Pathname do
+        # Check if path is considered disk image metadata.
         def dmg_metadata?
           DMG_METADATA.include?(cleanpath.ascend.to_a.last.to_s)
         end
 
-        # symlinks to system directories (commonly to /Applications)
+        # Check if path is a symlink to a system directory (commonly to /Applications).
         def system_dir_symlink?
           symlink? && MacOS.system_dir?(dirname.join(readlink))
         end
@@ -48,9 +51,9 @@ module UnpackStrategy
     end
     private_constant :Bom
 
-    using Bom
-
+    # Strategy for unpacking a volume mounted from a disk image.
     class Mount
+      using Bom
       include UnpackStrategy
 
       def eject(verbose: false)
diff --git a/Library/Homebrew/unpack_strategy/executable.rb b/Library/Homebrew/unpack_strategy/executable.rb
index 82a84e1448..57e99908f0 100644
--- a/Library/Homebrew/unpack_strategy/executable.rb
+++ b/Library/Homebrew/unpack_strategy/executable.rb
@@ -3,6 +3,7 @@
 require_relative "uncompressed"
 
 module UnpackStrategy
+  # Strategy for unpacking executables.
   class Executable < Uncompressed
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/fossil.rb b/Library/Homebrew/unpack_strategy/fossil.rb
index 6b7a5d9310..ea7f2216b8 100644
--- a/Library/Homebrew/unpack_strategy/fossil.rb
+++ b/Library/Homebrew/unpack_strategy/fossil.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking Fossil repositories.
   class Fossil
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/generic_unar.rb b/Library/Homebrew/unpack_strategy/generic_unar.rb
index 347dd6ac19..5458141748 100644
--- a/Library/Homebrew/unpack_strategy/generic_unar.rb
+++ b/Library/Homebrew/unpack_strategy/generic_unar.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking archives with `unar`.
   class GenericUnar
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/git.rb b/Library/Homebrew/unpack_strategy/git.rb
index 4aefb640d3..c704f13a47 100644
--- a/Library/Homebrew/unpack_strategy/git.rb
+++ b/Library/Homebrew/unpack_strategy/git.rb
@@ -3,6 +3,7 @@
 require_relative "directory"
 
 module UnpackStrategy
+  # Strategy for unpacking Git repositories.
   class Git < Directory
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/gzip.rb b/Library/Homebrew/unpack_strategy/gzip.rb
index 5db11be724..8f576788d5 100644
--- a/Library/Homebrew/unpack_strategy/gzip.rb
+++ b/Library/Homebrew/unpack_strategy/gzip.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking gzip archives.
   class Gzip
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/jar.rb b/Library/Homebrew/unpack_strategy/jar.rb
index 9827cc62c1..8fc3a70476 100644
--- a/Library/Homebrew/unpack_strategy/jar.rb
+++ b/Library/Homebrew/unpack_strategy/jar.rb
@@ -3,6 +3,7 @@
 require_relative "uncompressed"
 
 module UnpackStrategy
+  # Strategy for unpacking Java archives.
   class Jar < Uncompressed
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/lha.rb b/Library/Homebrew/unpack_strategy/lha.rb
index 0527013208..d3bfcaf87e 100644
--- a/Library/Homebrew/unpack_strategy/lha.rb
+++ b/Library/Homebrew/unpack_strategy/lha.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking LHa archives.
   class Lha
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/lua_rock.rb b/Library/Homebrew/unpack_strategy/lua_rock.rb
index 70759c981e..8517b140e5 100644
--- a/Library/Homebrew/unpack_strategy/lua_rock.rb
+++ b/Library/Homebrew/unpack_strategy/lua_rock.rb
@@ -3,6 +3,7 @@
 require_relative "uncompressed"
 
 module UnpackStrategy
+  # Strategy for unpacking LuaRock archives.
   class LuaRock < Uncompressed
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/lzip.rb b/Library/Homebrew/unpack_strategy/lzip.rb
index 121dea7a77..687917cea4 100644
--- a/Library/Homebrew/unpack_strategy/lzip.rb
+++ b/Library/Homebrew/unpack_strategy/lzip.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking lzip archives.
   class Lzip
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/lzma.rb b/Library/Homebrew/unpack_strategy/lzma.rb
index 257fb75984..006fcfb741 100644
--- a/Library/Homebrew/unpack_strategy/lzma.rb
+++ b/Library/Homebrew/unpack_strategy/lzma.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking LZMA archives.
   class Lzma
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/mercurial.rb b/Library/Homebrew/unpack_strategy/mercurial.rb
index 4799a5e0c1..7e0d3b64d2 100644
--- a/Library/Homebrew/unpack_strategy/mercurial.rb
+++ b/Library/Homebrew/unpack_strategy/mercurial.rb
@@ -3,6 +3,7 @@
 require_relative "directory"
 
 module UnpackStrategy
+  # Strategy for unpacking Mercurial repositories.
   class Mercurial < Directory
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/microsoft_office_xml.rb b/Library/Homebrew/unpack_strategy/microsoft_office_xml.rb
index 869c0debbd..8c3463be08 100644
--- a/Library/Homebrew/unpack_strategy/microsoft_office_xml.rb
+++ b/Library/Homebrew/unpack_strategy/microsoft_office_xml.rb
@@ -3,6 +3,7 @@
 require_relative "uncompressed"
 
 module UnpackStrategy
+  # Strategy for unpacking Microsoft Office documents.
   class MicrosoftOfficeXml < Uncompressed
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/otf.rb b/Library/Homebrew/unpack_strategy/otf.rb
index ff4c20662b..17b55ed7a6 100644
--- a/Library/Homebrew/unpack_strategy/otf.rb
+++ b/Library/Homebrew/unpack_strategy/otf.rb
@@ -3,6 +3,7 @@
 require_relative "uncompressed"
 
 module UnpackStrategy
+  # Strategy for unpacking OpenType fonts.
   class Otf < Uncompressed
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/p7zip.rb b/Library/Homebrew/unpack_strategy/p7zip.rb
index 6110a275bc..df77933191 100644
--- a/Library/Homebrew/unpack_strategy/p7zip.rb
+++ b/Library/Homebrew/unpack_strategy/p7zip.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking P7ZIP archives.
   class P7Zip
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/pax.rb b/Library/Homebrew/unpack_strategy/pax.rb
index bd1fe0d1e7..89138e5779 100644
--- a/Library/Homebrew/unpack_strategy/pax.rb
+++ b/Library/Homebrew/unpack_strategy/pax.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking pax archives.
   class Pax
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/pkg.rb b/Library/Homebrew/unpack_strategy/pkg.rb
index 10ae040241..8dad4a4436 100644
--- a/Library/Homebrew/unpack_strategy/pkg.rb
+++ b/Library/Homebrew/unpack_strategy/pkg.rb
@@ -3,6 +3,7 @@
 require_relative "uncompressed"
 
 module UnpackStrategy
+  # Strategy for unpacking macOS package installers.
   class Pkg < Uncompressed
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/rar.rb b/Library/Homebrew/unpack_strategy/rar.rb
index 64604792a8..5863b07422 100644
--- a/Library/Homebrew/unpack_strategy/rar.rb
+++ b/Library/Homebrew/unpack_strategy/rar.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking RAR archives.
   class Rar
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/self_extracting_executable.rb b/Library/Homebrew/unpack_strategy/self_extracting_executable.rb
index 298070fde3..9de9120b02 100644
--- a/Library/Homebrew/unpack_strategy/self_extracting_executable.rb
+++ b/Library/Homebrew/unpack_strategy/self_extracting_executable.rb
@@ -3,6 +3,7 @@
 require_relative "generic_unar"
 
 module UnpackStrategy
+  # Strategy for unpacking self-extracting executables.
   class SelfExtractingExecutable < GenericUnar
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/sit.rb b/Library/Homebrew/unpack_strategy/sit.rb
index 9f537d64e8..5ec16b48ab 100644
--- a/Library/Homebrew/unpack_strategy/sit.rb
+++ b/Library/Homebrew/unpack_strategy/sit.rb
@@ -3,6 +3,7 @@
 require_relative "generic_unar"
 
 module UnpackStrategy
+  # Strategy for unpacking Stuffit archives.
   class Sit < GenericUnar
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/subversion.rb b/Library/Homebrew/unpack_strategy/subversion.rb
index c9dbfdc644..0c90b36605 100644
--- a/Library/Homebrew/unpack_strategy/subversion.rb
+++ b/Library/Homebrew/unpack_strategy/subversion.rb
@@ -3,6 +3,7 @@
 require_relative "directory"
 
 module UnpackStrategy
+  # Strategy for unpacking Subversion repositories.
   class Subversion < Directory
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/tar.rb b/Library/Homebrew/unpack_strategy/tar.rb
index 17be99f406..25c30973dd 100644
--- a/Library/Homebrew/unpack_strategy/tar.rb
+++ b/Library/Homebrew/unpack_strategy/tar.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking tar archives.
   class Tar
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/ttf.rb b/Library/Homebrew/unpack_strategy/ttf.rb
index c3107d6594..54c6a6bd82 100644
--- a/Library/Homebrew/unpack_strategy/ttf.rb
+++ b/Library/Homebrew/unpack_strategy/ttf.rb
@@ -3,6 +3,7 @@
 require_relative "uncompressed"
 
 module UnpackStrategy
+  # Strategy for unpacking TrueType fonts.
   class Ttf < Uncompressed
     using Magic
 
diff --git a/Library/Homebrew/unpack_strategy/uncompressed.rb b/Library/Homebrew/unpack_strategy/uncompressed.rb
index be11b25c26..ea7f943a20 100644
--- a/Library/Homebrew/unpack_strategy/uncompressed.rb
+++ b/Library/Homebrew/unpack_strategy/uncompressed.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking uncompressed files.
   class Uncompressed
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/xar.rb b/Library/Homebrew/unpack_strategy/xar.rb
index 29d0e71783..69422eb660 100644
--- a/Library/Homebrew/unpack_strategy/xar.rb
+++ b/Library/Homebrew/unpack_strategy/xar.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking xar archives.
   class Xar
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/xz.rb b/Library/Homebrew/unpack_strategy/xz.rb
index a0ce3fbc16..29ac0c182d 100644
--- a/Library/Homebrew/unpack_strategy/xz.rb
+++ b/Library/Homebrew/unpack_strategy/xz.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking xz archives.
   class Xz
     include UnpackStrategy
 
diff --git a/Library/Homebrew/unpack_strategy/zip.rb b/Library/Homebrew/unpack_strategy/zip.rb
index 80eee72886..e58e556c7c 100644
--- a/Library/Homebrew/unpack_strategy/zip.rb
+++ b/Library/Homebrew/unpack_strategy/zip.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module UnpackStrategy
+  # Strategy for unpacking ZIP archives.
   class Zip
     include UnpackStrategy
 

From 45e3d58e96442a9acad2761d213dd05d95b09a1d Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 02:02:31 +0200
Subject: [PATCH 006/111] Document `Bintray`.

---
 Library/Homebrew/bintray.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/bintray.rb b/Library/Homebrew/bintray.rb
index 5d4b05f36a..26b9583184 100644
--- a/Library/Homebrew/bintray.rb
+++ b/Library/Homebrew/bintray.rb
@@ -3,6 +3,9 @@
 require "utils/curl"
 require "json"
 
+# Bintray API client.
+#
+# @api private
 class Bintray
   include Context
 

From a231116252657f879578627d7a77a4fcc3ead2e5 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 02:06:33 +0200
Subject: [PATCH 007/111] Document `PATH`.

---
 Library/Homebrew/PATH.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/PATH.rb b/Library/Homebrew/PATH.rb
index 4f46be178a..ac9f408a93 100644
--- a/Library/Homebrew/PATH.rb
+++ b/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

From 9db7825606fc0b66f2cdcce95dcc69503e3793f5 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 02:51:51 +0200
Subject: [PATCH 008/111] Document `Build`.

---
 Library/Homebrew/build.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/build.rb b/Library/Homebrew/build.rb
index 42079473d2..a5e3740184 100644
--- a/Library/Homebrew/build.rb
+++ b/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
 

From 81295422778819f6e08d0a51243a9b92fb7669b6 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 02:55:39 +0200
Subject: [PATCH 009/111] Document `BuildOptions`.

---
 Library/Homebrew/build_options.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/build_options.rb b/Library/Homebrew/build_options.rb
index fc81bb8218..be0da2a8ef 100644
--- a/Library/Homebrew/build_options.rb
+++ b/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)

From 608760908fb2006765152295c420dbff58f88356 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 03:12:03 +0200
Subject: [PATCH 010/111] Document `Commands`.

---
 Library/Homebrew/commands.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/commands.rb b/Library/Homebrew/commands.rb
index fe279bb777..30098ae92b 100644
--- a/Library/Homebrew/commands.rb
+++ b/Library/Homebrew/commands.rb
@@ -2,6 +2,9 @@
 
 require "cask/cmd"
 
+# Helper functions for commands.
+#
+# @api private
 module Commands
   module_function
 

From a5c1f38186573ecbd8d4b0f6b2c28e5b1e2cc922 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 03:21:41 +0200
Subject: [PATCH 011/111] Document `CompilerFailure` and `CompilerSelector`.

---
 Library/Homebrew/compilers.rb | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Library/Homebrew/compilers.rb b/Library/Homebrew/compilers.rb
index 25a9a42147..ca19f896f5 100644
--- a/Library/Homebrew/compilers.rb
+++ b/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
 

From 9cab71a62f180f2b1f85c60c2b7b9d848ec568cf Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 03:26:20 +0200
Subject: [PATCH 012/111] Document `Context`.

---
 Library/Homebrew/context.rb | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Library/Homebrew/context.rb b/Library/Homebrew/context.rb
index c8c70ac7b8..46407ed5bb 100644
--- a/Library/Homebrew/context.rb
+++ b/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

From 23cbb79810c00c024a812f65b16567d5b4280232 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 03:45:47 +0200
Subject: [PATCH 013/111] Document `Debrew`.

---
 Library/Homebrew/debrew.rb | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Library/Homebrew/debrew.rb b/Library/Homebrew/debrew.rb
index 33209cffe1..6382cbca0c 100644
--- a/Library/Homebrew/debrew.rb
+++ b/Library/Homebrew/debrew.rb
@@ -3,11 +3,15 @@
 require "mutex_m"
 require "debrew/irb"
 
+# Helper module for debugging formulae.
+#
+# @api private
 module Debrew
   extend Mutex_m
 
   Ignorable = Module.new.freeze
 
+  # Module for allowing to ignore exceptions.
   module Raise
     def raise(*)
       super
@@ -19,6 +23,7 @@ module Debrew
     alias fail raise
   end
 
+  # Module for allowing to debug formulae.
   module Formula
     def install
       Debrew.debrew { super }
@@ -33,6 +38,7 @@ module Debrew
     end
   end
 
+  # Module for displaying a debugging menu.
   class Menu
     Entry = Struct.new(:name, :action)
 

From 77a8c1b67f45610204052211c2d025dc57eb0360 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 03:48:04 +0200
Subject: [PATCH 014/111] Document `Dependable`.

---
 Library/Homebrew/dependable.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/dependable.rb b/Library/Homebrew/dependable.rb
index 2b97e7db75..89dfe083c2 100644
--- a/Library/Homebrew/dependable.rb
+++ b/Library/Homebrew/dependable.rb
@@ -2,6 +2,9 @@
 
 require "options"
 
+# Shared functions for classes which can be depended upon.
+#
+# @api private
 module Dependable
   # `:run` and `:linked` are no longer used but keep them here to avoid them being
   # misused in future.

From 50f40b597809306b5b635326b76dc95b02ec505b Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 03:52:11 +0200
Subject: [PATCH 015/111] Document `Dependencies` and `Requirements`.

---
 Library/Homebrew/dependencies.rb | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Library/Homebrew/dependencies.rb b/Library/Homebrew/dependencies.rb
index 476d1b53ec..6a39871b13 100644
--- a/Library/Homebrew/dependencies.rb
+++ b/Library/Homebrew/dependencies.rb
@@ -3,6 +3,9 @@
 require "delegate"
 require "cask_dependent"
 
+# A collection of dependencies.
+#
+# @api private
 class Dependencies < DelegateClass(Array)
   def initialize(*args)
     super(args)
@@ -35,6 +38,9 @@ class Dependencies < DelegateClass(Array)
   end
 end
 
+# A collection of requirements.
+#
+# @api private
 class Requirements < DelegateClass(Set)
   def initialize(*args)
     super(Set.new(args))

From ad4e97391c7292a8d3d9ac62d6e9f93afc6dc605 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 04:03:15 +0200
Subject: [PATCH 016/111] Document `DependenciesHelpers`.

---
 Library/Homebrew/dependencies_helpers.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/dependencies_helpers.rb b/Library/Homebrew/dependencies_helpers.rb
index fb6f13e9d1..998cef14a2 100644
--- a/Library/Homebrew/dependencies_helpers.rb
+++ b/Library/Homebrew/dependencies_helpers.rb
@@ -2,6 +2,9 @@
 
 require "cask_dependent"
 
+# Helper functions for dependencies.
+#
+# @api private
 module DependenciesHelpers
   def args_includes_ignores(args)
     includes = []

From 8f468d0c13bbfac77cdae6e901b99eb871aec1c3 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 04:11:34 +0200
Subject: [PATCH 017/111] Document `Descriptions`.

---
 Library/Homebrew/descriptions.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/descriptions.rb b/Library/Homebrew/descriptions.rb
index 46b7f2ef31..6ba21bed47 100644
--- a/Library/Homebrew/descriptions.rb
+++ b/Library/Homebrew/descriptions.rb
@@ -5,6 +5,9 @@ require "formula_versions"
 require "search"
 require "searchable"
 
+# Helper class for printing and searching descriptions.
+#
+# @api private
 class Descriptions
   extend Homebrew::Search
 

From 1ea50d08fa3bc5780e3048d964e3fa4ea86bd841 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 04:06:29 +0200
Subject: [PATCH 018/111] Document `Dependency` and `TapDependency`.

---
 Library/Homebrew/dependency.rb | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Library/Homebrew/dependency.rb b/Library/Homebrew/dependency.rb
index d97a5a22a1..29a2284c7f 100644
--- a/Library/Homebrew/dependency.rb
+++ b/Library/Homebrew/dependency.rb
@@ -3,6 +3,8 @@
 require "dependable"
 
 # A dependency on another Homebrew formula.
+#
+# @api private
 class Dependency
   extend Forwardable
   include Dependable
@@ -10,6 +12,7 @@ class Dependency
   attr_reader :name, :tags, :env_proc, :option_names
 
   DEFAULT_ENV_PROC = proc {}.freeze
+  private_constant :DEFAULT_ENV_PROC
 
   def initialize(name, tags = [], env_proc = DEFAULT_ENV_PROC, option_names = [name])
     raise ArgumentError, "Dependency must have a name!" unless name
@@ -176,6 +179,7 @@ class Dependency
   end
 end
 
+# A dependency on another Homebrew formula in a specific tap.
 class TapDependency < Dependency
   attr_reader :tap
 

From f98223ba1a77e2bddf866f68e72a964da2d8ffb8 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 04:35:58 +0200
Subject: [PATCH 019/111] Document `EnvConfig`.

---
 Library/Homebrew/env_config.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb
index f6a578b1ac..a8cc41682f 100644
--- a/Library/Homebrew/env_config.rb
+++ b/Library/Homebrew/env_config.rb
@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Homebrew
+  # Helper module for querying Homebrew-specific environment variables.
+  #
+  # @api private
   module EnvConfig
     module_function
 

From 0240128f29df066789aeb6aa83f0dbeb590e3134 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 05:28:26 +0200
Subject: [PATCH 020/111] Document exceptions.

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

diff --git a/Library/Homebrew/exceptions.rb b/Library/Homebrew/exceptions.rb
index d0016cb1e2..137f593c71 100644
--- a/Library/Homebrew/exceptions.rb
+++ b/Library/Homebrew/exceptions.rb
@@ -3,6 +3,7 @@
 require "shellwords"
 require "utils"
 
+# Raised when a command is used wrong.
 class UsageError < RuntimeError
   attr_reader :reason
 
@@ -19,12 +20,14 @@ class UsageError < RuntimeError
   end
 end
 
+# Raised when a command expects a formula and none was specified.
 class FormulaUnspecifiedError < UsageError
   def initialize
     super "this command requires a formula argument"
   end
 end
 
+# Raised when a command expects a keg and none was specified.
 class KegUnspecifiedError < UsageError
   def initialize
     super "this command requires a keg argument"
@@ -35,6 +38,7 @@ class MultipleVersionsInstalledError < RuntimeError; end
 
 class NotAKegError < RuntimeError; end
 
+# Raised when a keg doesn't exist.
 class NoSuchKegError < RuntimeError
   attr_reader :name
 
@@ -44,6 +48,7 @@ class NoSuchKegError < RuntimeError
   end
 end
 
+# Raised when an invalid attribute is used in a formula.
 class FormulaValidationError < StandardError
   attr_reader :attr, :formula
 
@@ -56,10 +61,14 @@ end
 
 class FormulaSpecificationError < StandardError; end
 
+# Raised when a deprecated method is used.
+#
+# @api private
 class MethodDeprecatedError < StandardError
   attr_accessor :issues_url
 end
 
+# Raised when a formula is not available.
 class FormulaUnavailableError < RuntimeError
   attr_reader :name
   attr_accessor :dependent
@@ -79,6 +88,9 @@ class FormulaUnavailableError < RuntimeError
   end
 end
 
+# Shared methods for formula class errors.
+#
+# @api private
 module FormulaClassUnavailableErrorModule
   attr_reader :path, :class_name, :class_list
 
@@ -107,6 +119,7 @@ module FormulaClassUnavailableErrorModule
   end
 end
 
+# Raised when a formula does not contain a formula class.
 class FormulaClassUnavailableError < FormulaUnavailableError
   include FormulaClassUnavailableErrorModule
 
@@ -118,6 +131,9 @@ class FormulaClassUnavailableError < FormulaUnavailableError
   end
 end
 
+# Shared methods for formula unreadable errors.
+#
+# @api private
 module FormulaUnreadableErrorModule
   attr_reader :formula_error
 
@@ -126,6 +142,7 @@ module FormulaUnreadableErrorModule
   end
 end
 
+# Raised when a formula is unreadable.
 class FormulaUnreadableError < FormulaUnavailableError
   include FormulaUnreadableErrorModule
 
@@ -135,6 +152,7 @@ class FormulaUnreadableError < FormulaUnavailableError
   end
 end
 
+# Raised when a formula in a specific tap is unavailable.
 class TapFormulaUnavailableError < FormulaUnavailableError
   attr_reader :tap, :user, :repo
 
@@ -152,6 +170,7 @@ class TapFormulaUnavailableError < FormulaUnavailableError
   end
 end
 
+# Raised when a formula in a specific tap does not contain a formula class.
 class TapFormulaClassUnavailableError < TapFormulaUnavailableError
   include FormulaClassUnavailableErrorModule
 
@@ -165,6 +184,7 @@ class TapFormulaClassUnavailableError < TapFormulaUnavailableError
   end
 end
 
+# Raised when a formula in a specific tap is unreadable.
 class TapFormulaUnreadableError < TapFormulaUnavailableError
   include FormulaUnreadableErrorModule
 
@@ -174,6 +194,7 @@ class TapFormulaUnreadableError < TapFormulaUnavailableError
   end
 end
 
+# Raised when a formula with the same name is found multiple taps.
 class TapFormulaAmbiguityError < RuntimeError
   attr_reader :name, :paths, :formulae
 
@@ -192,6 +213,7 @@ class TapFormulaAmbiguityError < RuntimeError
   end
 end
 
+# Raised when a formula's old name in a specific tap is found in multiple taps.
 class TapFormulaWithOldnameAmbiguityError < RuntimeError
   attr_reader :name, :possible_tap_newname_formulae, :taps
 
@@ -212,6 +234,7 @@ class TapFormulaWithOldnameAmbiguityError < RuntimeError
   end
 end
 
+# Raised when a tap is unavailable.
 class TapUnavailableError < RuntimeError
   attr_reader :name
 
@@ -224,6 +247,7 @@ class TapUnavailableError < RuntimeError
   end
 end
 
+# Raised when a tap's remote does not match the actual remote.
 class TapRemoteMismatchError < RuntimeError
   attr_reader :name, :expected_remote, :actual_remote
 
@@ -239,6 +263,7 @@ class TapRemoteMismatchError < RuntimeError
   end
 end
 
+# Raised when a tap is already installed.
 class TapAlreadyTappedError < RuntimeError
   attr_reader :name
 
@@ -251,6 +276,7 @@ class TapAlreadyTappedError < RuntimeError
   end
 end
 
+# Raised when another Homebrew operation is already in progress.
 class OperationInProgressError < RuntimeError
   def initialize(name)
     message = <<~EOS
@@ -265,12 +291,14 @@ end
 
 class CannotInstallFormulaError < RuntimeError; end
 
+# Raised when a formula installation was already attempted.
 class FormulaInstallationAlreadyAttemptedError < RuntimeError
   def initialize(formula)
     super "Formula installation already attempted: #{formula.full_name}"
   end
 end
 
+# Raised when there are unsatisfied requirements.
 class UnsatisfiedRequirements < RuntimeError
   def initialize(reqs)
     if reqs.length == 1
@@ -281,6 +309,7 @@ class UnsatisfiedRequirements < RuntimeError
   end
 end
 
+# Raised when a formula conflicts with another one.
 class FormulaConflictError < RuntimeError
   attr_reader :formula, :conflicts
 
@@ -313,6 +342,7 @@ class FormulaConflictError < RuntimeError
   end
 end
 
+# Raise when the Python version cannot be detected automatically.
 class FormulaUnknownPythonError < RuntimeError
   def initialize(formula)
     super <<~EOS
@@ -325,6 +355,7 @@ class FormulaUnknownPythonError < RuntimeError
   end
 end
 
+# Raise when two Python versions are detected simultaneously.
 class FormulaAmbiguousPythonError < RuntimeError
   def initialize(formula)
     super <<~EOS
@@ -336,6 +367,7 @@ class FormulaAmbiguousPythonError < RuntimeError
   end
 end
 
+# Raised when an error occurs during a formula build.
 class BuildError < RuntimeError
   attr_reader :cmd, :args, :env
   attr_accessor :formula, :options
@@ -561,12 +593,14 @@ class ChecksumMismatchError < RuntimeError
   end
 end
 
+# Raised when a resource is missing.
 class ResourceMissingError < ArgumentError
   def initialize(formula, resource)
     super "#{formula.full_name} does not define resource #{resource.inspect}"
   end
 end
 
+# Raised when a resource is specified multiple times.
 class DuplicateResourceError < ArgumentError
   def initialize(resource)
     super "Resource #{resource.inspect} is defined more than once"
@@ -576,6 +610,7 @@ end
 # Raised when a single patch file is not found and apply hasn't been specified.
 class MissingApplyError < RuntimeError; end
 
+# Raised when a bottle does not contain a formula file.
 class BottleFormulaUnavailableError < RuntimeError
   def initialize(bottle_path, formula_path)
     super <<~EOS
@@ -604,6 +639,7 @@ class ChildProcessError < RuntimeError
   end
 end
 
+# Raised when a macOS version is unsupported.
 class MacOSVersionError < RuntimeError
   attr_reader :version
 

From 8957422d86aac251a887de19715fffb5b011ed6b Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 02:53:57 +0200
Subject: [PATCH 021/111] Document `Caveats`.

---
 Library/Homebrew/caveats.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/caveats.rb b/Library/Homebrew/caveats.rb
index 1b4e96d5e6..01ad2bd278 100644
--- a/Library/Homebrew/caveats.rb
+++ b/Library/Homebrew/caveats.rb
@@ -2,6 +2,9 @@
 
 require "language/python"
 
+# A formula's caveats.
+#
+# @api private
 class Caveats
   extend Forwardable
 

From 78b09a278d1571d5fa6c225c901584f0943f0b7e Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 02:58:03 +0200
Subject: [PATCH 022/111] Document `Checksum`.

---
 Library/Homebrew/checksum.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/checksum.rb b/Library/Homebrew/checksum.rb
index fe0960df4a..84c6c62342 100644
--- a/Library/Homebrew/checksum.rb
+++ b/Library/Homebrew/checksum.rb
@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# A formula's checksum.
+#
+# @api private
 class Checksum
   extend Forwardable
 

From e2b784bb98164bb0383bca19482cee3480f30f3b Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 04:53:36 +0200
Subject: [PATCH 023/111] Mark `Fetch` as private.

---
 Library/Homebrew/fetch.rb | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Library/Homebrew/fetch.rb b/Library/Homebrew/fetch.rb
index 7b0e76cd85..717537cbc1 100644
--- a/Library/Homebrew/fetch.rb
+++ b/Library/Homebrew/fetch.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Homebrew
+  # @api private
   module Fetch
     def fetch_bottle?(f, args:)
       return true if args.force_bottle? && f.bottle

From 3e60cb0d8c99f545197873988f59445a0fd342fb Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 05:15:22 +0200
Subject: [PATCH 024/111] Document `Assertions`.

---
 Library/Homebrew/formula_assertions.rb | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Library/Homebrew/formula_assertions.rb b/Library/Homebrew/formula_assertions.rb
index 55592f2214..fdcfa86573 100644
--- a/Library/Homebrew/formula_assertions.rb
+++ b/Library/Homebrew/formula_assertions.rb
@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Homebrew
+  # Helper functions available in formula `test` blocks.
+  #
+  # @api private
   module Assertions
     include Context
 
@@ -8,6 +11,7 @@ module Homebrew
     include ::Test::Unit::Assertions
 
     # Returns the output of running cmd, and asserts the exit status
+    # @api public
     def shell_output(cmd, result = 0)
       ohai cmd
       output = `#{cmd}`
@@ -19,7 +23,8 @@ module Homebrew
     end
 
     # Returns the output of running the cmd with the optional input, and
-    # optionally asserts the exit status
+    # optionally asserts the exit status.
+    # @api public
     def pipe_output(cmd, input = nil, result = nil)
       ohai cmd
       output = IO.popen(cmd, "w+") do |pipe|

From 603bbd9a959d6064b74eb89b2adcfe1a5faa5b49 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 05:52:29 +0200
Subject: [PATCH 025/111] Document `FormulaCellarChecks`.

---
 Library/Homebrew/formula_cellar_checks.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/formula_cellar_checks.rb b/Library/Homebrew/formula_cellar_checks.rb
index d81f6d70e7..4bed3fc569 100644
--- a/Library/Homebrew/formula_cellar_checks.rb
+++ b/Library/Homebrew/formula_cellar_checks.rb
@@ -2,6 +2,9 @@
 
 require "utils/shell"
 
+# Checks to perform on a formula's cellar.
+#
+# @api private
 module FormulaCellarChecks
   def check_env_path(bin)
     # warn the user if stuff was installed outside of their PATH

From 3d1f0ded399b57049e81b44dd80f2d508b6b3eb4 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 05:53:46 +0200
Subject: [PATCH 026/111] Document `FormulaCreator`.

---
 Library/Homebrew/formula_creator.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/formula_creator.rb b/Library/Homebrew/formula_creator.rb
index 0be15b4f88..4153c5e096 100644
--- a/Library/Homebrew/formula_creator.rb
+++ b/Library/Homebrew/formula_creator.rb
@@ -4,6 +4,9 @@ require "digest"
 require "erb"
 
 module Homebrew
+  # Class for generating a formula from a template.
+  #
+  # @api private
   class FormulaCreator
     attr_reader :args, :url, :sha256, :desc, :homepage
     attr_accessor :name, :version, :tap, :path, :mode, :license

From b6b102effbfe6abf5dfac4dfcc5643bd4784d775 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 06:01:54 +0200
Subject: [PATCH 027/111] Document `FreePort`.

---
 Library/Homebrew/formula_free_port.rb | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/Library/Homebrew/formula_free_port.rb b/Library/Homebrew/formula_free_port.rb
index 894b5cf8c2..2067ca287f 100644
--- a/Library/Homebrew/formula_free_port.rb
+++ b/Library/Homebrew/formula_free_port.rb
@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
-module Homebrew
-  module FreePort
-    require "socket"
+require "socket"
 
+module Homebrew
+  # Helper function for finding a free port.
+  #
+  # @api private
+  module FreePort
+    # Returns a free port.
+    # @api public
     def free_port
       server = TCPServer.new 0
       _, port, = server.addr

From 011649a785caf3d51400a8282a3c7a01e7481443 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 06:04:12 +0200
Subject: [PATCH 028/111] Document `FormulaInfo`.

---
 Library/Homebrew/formula_info.rb | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Library/Homebrew/formula_info.rb b/Library/Homebrew/formula_info.rb
index 4243d6d392..9165643948 100644
--- a/Library/Homebrew/formula_info.rb
+++ b/Library/Homebrew/formula_info.rb
@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-# Formula info drawn from an external `brew info --json` call
-
+# Formula information drawn from an external `brew info --json` call.
+#
+# @api private
 class FormulaInfo
   # The whole info structure parsed from the JSON
   attr_accessor :info

From 528122638c1b58f4ed7f1b66975c79ff34ef22c7 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 06:05:08 +0200
Subject: [PATCH 029/111] Document `FormulaInstaller`.

---
 Library/Homebrew/formula_installer.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/formula_installer.rb b/Library/Homebrew/formula_installer.rb
index 684ffa3bbe..0da32495f1 100644
--- a/Library/Homebrew/formula_installer.rb
+++ b/Library/Homebrew/formula_installer.rb
@@ -21,6 +21,9 @@ require "cmd/install"
 require "find"
 require "utils/spdx"
 
+# Installer for a formula.
+#
+# @api private
 class FormulaInstaller
   include FormulaCellarChecks
   extend Predicable

From e5d72ecc6ce59b1c2f1e049cb8e629a795aa43dd Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 06:08:56 +0200
Subject: [PATCH 030/111] Document `FormulaPin`.

---
 Library/Homebrew/formula_pin.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/formula_pin.rb b/Library/Homebrew/formula_pin.rb
index f9c54097fa..613a51fc81 100644
--- a/Library/Homebrew/formula_pin.rb
+++ b/Library/Homebrew/formula_pin.rb
@@ -2,6 +2,9 @@
 
 require "keg"
 
+# Helper functions for pinning a formula.
+#
+# @api private
 class FormulaPin
   def initialize(f)
     @f = f

From 3851087d01d880ff84cf3a2c666b0b9b6c2fa2d5 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 06:09:57 +0200
Subject: [PATCH 031/111] Document `FormulaVersions`.

---
 Library/Homebrew/formula_versions.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/formula_versions.rb b/Library/Homebrew/formula_versions.rb
index 2fb219d85d..ecd67d5270 100644
--- a/Library/Homebrew/formula_versions.rb
+++ b/Library/Homebrew/formula_versions.rb
@@ -2,6 +2,9 @@
 
 require "formula"
 
+# Helper class for traversing a formula's previous versions.
+#
+# @api private
 class FormulaVersions
   include Context
 

From fc6037ce5372c3cd5d1124d2b9d79e69bf0d9ec2 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 06:10:42 +0200
Subject: [PATCH 032/111] Document `Formulary`.

---
 Library/Homebrew/formulary.rb | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Library/Homebrew/formulary.rb b/Library/Homebrew/formulary.rb
index c9e147a91e..f71354f089 100644
--- a/Library/Homebrew/formulary.rb
+++ b/Library/Homebrew/formulary.rb
@@ -6,7 +6,8 @@ require "tab"
 
 # The Formulary is responsible for creating instances of {Formula}.
 # It is not meant to be used directly from formulae.
-
+#
+# @api private
 module Formulary
   extend Cachable
 
@@ -150,7 +151,7 @@ module Formulary
     end
   end
 
-  # Loads formulae from bottles.
+  # Loads a formula from a bottle.
   class BottleLoader < FormulaLoader
     def initialize(bottle_name)
       case bottle_name
@@ -187,6 +188,7 @@ module Formulary
     end
   end
 
+  # Loads a formula from a path to an alias.
   class AliasLoader < FormulaLoader
     def initialize(alias_path)
       path = alias_path.resolved_path
@@ -298,6 +300,7 @@ module Formulary
     end
   end
 
+  # Pseudo-loader which will raise a `FormulaUnavailableError` when trying to load the corresponding formula.
   class NullLoader < FormulaLoader
     def initialize(name)
       super name, Formulary.core_path(name)

From 73c05f36ab6a24683c4f797aef4b3399e626ab4c Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 18:42:42 +0200
Subject: [PATCH 033/111] Document `InstallRenamed`.

---
 Library/Homebrew/install_renamed.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/install_renamed.rb b/Library/Homebrew/install_renamed.rb
index 9fa6f37fa2..ac891273a0 100644
--- a/Library/Homebrew/install_renamed.rb
+++ b/Library/Homebrew/install_renamed.rb
@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Helper module for installing default files.
+#
+# @api private
 module InstallRenamed
   def install_p(_, new_basename)
     super do |src, dst|

From 6a364c9e1fca507689f8f58eb50716d0eeff717d Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 18:45:48 +0200
Subject: [PATCH 034/111] Document `Keg`.

---
 Library/Homebrew/keg.rb | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Library/Homebrew/keg.rb b/Library/Homebrew/keg.rb
index 4698dcfa0c..00668f1250 100644
--- a/Library/Homebrew/keg.rb
+++ b/Library/Homebrew/keg.rb
@@ -6,9 +6,13 @@ require "lock_file"
 require "ostruct"
 require "extend/cachable"
 
+# Installation prefix of a formula.
+#
+# @api private
 class Keg
   extend Cachable
 
+  # Error for when a keg is already linked.
   class AlreadyLinkedError < RuntimeError
     def initialize(keg)
       super <<~EOS
@@ -18,6 +22,7 @@ class Keg
     end
   end
 
+  # Error for when a keg cannot be linked.
   class LinkError < RuntimeError
     attr_reader :keg, :src, :dst
 
@@ -31,6 +36,7 @@ class Keg
     end
   end
 
+  # Error for when a file already exists or belongs to another keg.
   class ConflictError < LinkError
     def suggestion
       conflict = Keg.for(dst)
@@ -58,6 +64,7 @@ class Keg
     end
   end
 
+  # Error for when a directory is not writable.
   class DirectoryNotWritableError < LinkError
     def to_s
       <<~EOS

From 609c5e4a35f6a66f61f0aef749758385c639f178 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 18:58:28 +0200
Subject: [PATCH 035/111] Document `Language::Go`.

---
 Library/Homebrew/language/go.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/language/go.rb b/Library/Homebrew/language/go.rb
index 84188c0ef4..2b4a0399d8 100644
--- a/Library/Homebrew/language/go.rb
+++ b/Library/Homebrew/language/go.rb
@@ -3,6 +3,9 @@
 require "resource"
 
 module Language
+  # Helper functions for Go formulae.
+  #
+  # @api public
   module Go
     # Given a set of resources, stages them to a gopath for
     # building go software.

From b18700625c7d97bc13a55b2c767decffb74d72a0 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 18:58:40 +0200
Subject: [PATCH 036/111] Document `Language::Java`.

---
 Library/Homebrew/language/java.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/language/java.rb b/Library/Homebrew/language/java.rb
index 1d2685d3fb..db9be69a22 100644
--- a/Library/Homebrew/language/java.rb
+++ b/Library/Homebrew/language/java.rb
@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Language
+  # Helper functions for Java formulae.
+  #
+  # @api public
   module Java
     def self.find_openjdk_formula(version = nil)
       can_be_newer = version&.end_with?("+")

From d50faba7445baf0b395b37ecbdb234c0e2fe5958 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 18:58:52 +0200
Subject: [PATCH 037/111] Document `Language::Node`.

---
 Library/Homebrew/language/node.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/language/node.rb b/Library/Homebrew/language/node.rb
index 75d61f8a4e..4f53e485f8 100644
--- a/Library/Homebrew/language/node.rb
+++ b/Library/Homebrew/language/node.rb
@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Language
+  # Helper functions for Node formulae.
+  #
+  # @api public
   module Node
     def self.npm_cache_config
       "cache=#{HOMEBREW_CACHE}/npm_cache"

From 4972b1935e22857679c008b8e7aca8f62ec93acb Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 18:59:02 +0200
Subject: [PATCH 038/111] Document `Language::Perl`.

---
 Library/Homebrew/language/perl.rb | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Library/Homebrew/language/perl.rb b/Library/Homebrew/language/perl.rb
index 7368b36ee6..c81ef65c51 100644
--- a/Library/Homebrew/language/perl.rb
+++ b/Library/Homebrew/language/perl.rb
@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 module Language
+  # Helper functions for Perl formulae.
+  #
+  # @api public
   module Perl
+    # Helper module for replacing `perl` shebangs.
     module Shebang
       module_function
 

From ceeb6e64927964cbb45d25f2bcee8c32ae823b50 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 19:10:06 +0200
Subject: [PATCH 039/111] Document `NamedArgs`.

---
 Library/Homebrew/cli/named_args.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/cli/named_args.rb b/Library/Homebrew/cli/named_args.rb
index 2597f4ba51..f6db49c90a 100644
--- a/Library/Homebrew/cli/named_args.rb
+++ b/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

From 931e1f4ee6a48e96b1ef1112ef1fb30db9ded780 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 19:45:33 +0200
Subject: [PATCH 040/111] Document `Migrator`.

---
 Library/Homebrew/migrator.rb | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Library/Homebrew/migrator.rb b/Library/Homebrew/migrator.rb
index e0903aa48f..bdf05f93bb 100644
--- a/Library/Homebrew/migrator.rb
+++ b/Library/Homebrew/migrator.rb
@@ -4,9 +4,13 @@ require "lock_file"
 require "keg"
 require "tab"
 
+# Helper class for migrating a formula from an old to a new name.
+#
+# @api private
 class Migrator
   include Context
 
+  # Error for when a migration is necessary.
   class MigrationNeededError < RuntimeError
     def initialize(formula)
       super <<~EOS
@@ -16,18 +20,21 @@ class Migrator
     end
   end
 
+  # Error for when a formula does not replace another formula.
   class MigratorNoOldnameError < RuntimeError
     def initialize(formula)
       super "#{formula.name} doesn't replace any formula."
     end
   end
 
+  # Error for when the old name's path does not exist.
   class MigratorNoOldpathError < RuntimeError
     def initialize(formula)
       super "#{HOMEBREW_CELLAR/formula.oldname} doesn't exist."
     end
   end
 
+  # Error for when a formula is migrated to a different tap without explicitly using its fully-qualified name.
   class MigratorDifferentTapsError < RuntimeError
     def initialize(formula, tap)
       msg = if tap.core_tap?

From 491ef34cc2d5fa66e7a56654389b1379a9b1239d Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 19:48:09 +0200
Subject: [PATCH 041/111] Document `Metafiles`.

---
 Library/Homebrew/metafiles.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/metafiles.rb b/Library/Homebrew/metafiles.rb
index 5159623f1d..95404030ff 100644
--- a/Library/Homebrew/metafiles.rb
+++ b/Library/Homebrew/metafiles.rb
@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Helper for checking if a file is considered a metadata file.
+#
+# @api private
 module Metafiles
   # https://github.com/github/markup#markups
   EXTENSIONS = Set.new(%w[

From 4d636d133559520e96b513d5b093775686ac9ccb Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 19:55:09 +0200
Subject: [PATCH 042/111] Document `MissingFormula`.

---
 Library/Homebrew/missing_formula.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/missing_formula.rb b/Library/Homebrew/missing_formula.rb
index 8205a56634..c69de457bb 100644
--- a/Library/Homebrew/missing_formula.rb
+++ b/Library/Homebrew/missing_formula.rb
@@ -3,6 +3,9 @@
 require "formulary"
 
 module Homebrew
+  # Helper module for checking if there is a reason a formula is missing.
+  #
+  # @api private
   module MissingFormula
     class << self
       def reason(name, silent: false, show_info: false)

From 3a04377b51bc5c36faa37d8141211b060677e589 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 19:56:24 +0200
Subject: [PATCH 043/111] Document `LinkageChecker`.

---
 Library/Homebrew/linkage_checker.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/linkage_checker.rb b/Library/Homebrew/linkage_checker.rb
index 65263161d9..9948086f22 100644
--- a/Library/Homebrew/linkage_checker.rb
+++ b/Library/Homebrew/linkage_checker.rb
@@ -5,6 +5,9 @@ require "formula"
 require "linkage_cache_store"
 require "fiddle"
 
+# Check for broken/missing linkage in a formula's keg.
+#
+# @api private
 class LinkageChecker
   attr_reader :undeclared_deps, :keg, :formula, :store
 

From b9894e22417578e7b61ec61d3f95ee89b5fc9b90 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 17 Aug 2020 20:06:08 +0200
Subject: [PATCH 044/111] Document `Patch`.

---
 Library/Homebrew/patch.rb | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Library/Homebrew/patch.rb b/Library/Homebrew/patch.rb
index f2a92a0616..de60b4a87b 100644
--- a/Library/Homebrew/patch.rb
+++ b/Library/Homebrew/patch.rb
@@ -3,6 +3,9 @@
 require "resource"
 require "erb"
 
+# Helper module for creating patches.
+#
+# @api private
 module Patch
   def self.create(strip, src, &block)
     case strip
@@ -52,6 +55,9 @@ module Patch
   end
 end
 
+# An abstract class representing a patch embedded into a formula.
+#
+# @api private
 class EmbeddedPatch
   attr_writer :owner
   attr_reader :strip
@@ -77,6 +83,9 @@ class EmbeddedPatch
   end
 end
 
+# A patch at the `__END__` of a formula file.
+#
+# @api private
 class DATAPatch < EmbeddedPatch
   attr_accessor :path
 
@@ -100,6 +109,9 @@ class DATAPatch < EmbeddedPatch
   end
 end
 
+# A string containing a patch.
+#
+# @api private
 class StringPatch < EmbeddedPatch
   def initialize(strip, str)
     super(strip)
@@ -111,6 +123,9 @@ class StringPatch < EmbeddedPatch
   end
 end
 
+# A string containing a patch.
+#
+# @api private
 class ExternalPatch
   extend Forwardable
 
@@ -170,7 +185,11 @@ class ExternalPatch
   end
 end
 
+# A legacy patch.
+#
 # Legacy patches have no checksum and are not cached.
+#
+# @api private
 class LegacyPatch < ExternalPatch
   def initialize(strip, url)
     odeprecated "legacy patches", "'patch do' blocks"

From f55debaeedf7770728f18316da6f2f3cb7fa6f37 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 18 Aug 2020 02:39:52 +0200
Subject: [PATCH 045/111] Document `Readall`.

---
 Library/Homebrew/readall.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/readall.rb b/Library/Homebrew/readall.rb
index 491c406cbb..d1e0a007bf 100644
--- a/Library/Homebrew/readall.rb
+++ b/Library/Homebrew/readall.rb
@@ -3,6 +3,9 @@
 require "formula"
 require "cask/cask_loader"
 
+# Helper module for validating syntax in taps.
+#
+# @api private
 module Readall
   class << self
     def valid_ruby_syntax?(ruby_files)

From c975ff98a0734b40475b25040fdd198a187d5e7e Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 18 Aug 2020 03:02:33 +0200
Subject: [PATCH 046/111] Document `Requirement`.

---
 Library/Homebrew/requirement.rb | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/Library/Homebrew/requirement.rb b/Library/Homebrew/requirement.rb
index 693c749a0d..d4bb330119 100644
--- a/Library/Homebrew/requirement.rb
+++ b/Library/Homebrew/requirement.rb
@@ -6,8 +6,10 @@ require "dependencies"
 require "build_environment"
 
 # A base class for non-formula requirements needed by formulae.
-# A "fatal" requirement is one that will fail the build if it is not present.
-# By default, Requirements are non-fatal.
+# A fatal requirement is one that will fail the build if it is not present.
+# By default, requirements are non-fatal.
+#
+# @api private
 class Requirement
   include Dependable
 
@@ -162,7 +164,7 @@ class Requirement
       return @satisfied if options.nil? && !block_given?
 
       options = {} if options.nil?
-      @satisfied = Requirement::Satisfier.new(options, &block)
+      @satisfied = Satisfier.new(options, &block)
     end
 
     def env(*settings, &block)
@@ -174,6 +176,7 @@ class Requirement
     end
   end
 
+  # Helper class for evaluating whether a requirement is satisfied.
   class Satisfier
     def initialize(options, &block)
       case options
@@ -201,6 +204,7 @@ class Requirement
       end
     end
   end
+  private_constant :Satisfier
 
   class << self
     # Expand the requirements of dependent recursively, optionally yielding

From 60d8e892fccec423c71512deff22106b21870242 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 18 Aug 2020 23:15:28 +0200
Subject: [PATCH 047/111] Document `ArchRequirement`.

---
 Library/Homebrew/requirements/arch_requirement.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/requirements/arch_requirement.rb b/Library/Homebrew/requirements/arch_requirement.rb
index 03a988c76b..dc9d81320f 100644
--- a/Library/Homebrew/requirements/arch_requirement.rb
+++ b/Library/Homebrew/requirements/arch_requirement.rb
@@ -2,6 +2,9 @@
 
 require "requirement"
 
+# A requirement on a specific architecture.
+#
+# @api private
 class ArchRequirement < Requirement
   fatal true
 

From eed1296d07df943e7ffd9fca20299e4d1e9f0f18 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 06:50:46 +0200
Subject: [PATCH 048/111] Document `CodesignRequirement`.

---
 Library/Homebrew/requirements/codesign_requirement.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/requirements/codesign_requirement.rb b/Library/Homebrew/requirements/codesign_requirement.rb
index b3643e6f23..dbec98dba9 100644
--- a/Library/Homebrew/requirements/codesign_requirement.rb
+++ b/Library/Homebrew/requirements/codesign_requirement.rb
@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# A requirement on a code-signing identity.
+#
+# @api private
 class CodesignRequirement < Requirement
   fatal true
 

From 0d96616daa6a0a27b4922b57a00f636a91640d33 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 06:50:53 +0200
Subject: [PATCH 049/111] Document `JavaRequirement`.

---
 Library/Homebrew/requirements/java_requirement.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/requirements/java_requirement.rb b/Library/Homebrew/requirements/java_requirement.rb
index a2e4fa2d9e..d6ba1a9332 100644
--- a/Library/Homebrew/requirements/java_requirement.rb
+++ b/Library/Homebrew/requirements/java_requirement.rb
@@ -2,6 +2,9 @@
 
 require "language/java"
 
+# A requirement on Java.
+#
+# @api private
 class JavaRequirement < Requirement
   fatal true
 

From 497a622654c5f99d5d53cddba0b7b49d77b0201f Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 06:51:02 +0200
Subject: [PATCH 050/111] Document `LinuxRequirement`.

---
 Library/Homebrew/requirements/linux_requirement.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/requirements/linux_requirement.rb b/Library/Homebrew/requirements/linux_requirement.rb
index 74daf4cf4a..04b644a398 100644
--- a/Library/Homebrew/requirements/linux_requirement.rb
+++ b/Library/Homebrew/requirements/linux_requirement.rb
@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# A requirement on Linux.
+#
+# @api private
 class LinuxRequirement < Requirement
   fatal true
 

From f755e084d8b03a8911c33c3c076f68af8ab28882 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 06:51:15 +0200
Subject: [PATCH 051/111] Document `MacOSRequirement`.

---
 Library/Homebrew/requirements/macos_requirement.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/requirements/macos_requirement.rb b/Library/Homebrew/requirements/macos_requirement.rb
index a723dda2c6..f8bdcf9150 100644
--- a/Library/Homebrew/requirements/macos_requirement.rb
+++ b/Library/Homebrew/requirements/macos_requirement.rb
@@ -2,6 +2,9 @@
 
 require "requirement"
 
+# A requirement on macOS.
+#
+# @api private
 class MacOSRequirement < Requirement
   fatal true
 

From 918eeb5493eb9796953e7bae1f7a07a87dbd7107 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 06:51:24 +0200
Subject: [PATCH 052/111] Document `OsxfuseRequirement`.

---
 Library/Homebrew/requirements/osxfuse_requirement.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/requirements/osxfuse_requirement.rb b/Library/Homebrew/requirements/osxfuse_requirement.rb
index 79712de53c..8371568fa0 100644
--- a/Library/Homebrew/requirements/osxfuse_requirement.rb
+++ b/Library/Homebrew/requirements/osxfuse_requirement.rb
@@ -2,6 +2,9 @@
 
 require "requirement"
 
+# A requirement on FUSE for macOS.
+#
+# @api private
 class OsxfuseRequirement < Requirement
   cask "osxfuse"
   fatal true

From 22eee279260d5b989c9d04e95ee2607e85a0c0a4 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 06:51:31 +0200
Subject: [PATCH 053/111] Document `TuntapRequirement`.

---
 Library/Homebrew/requirements/tuntap_requirement.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/requirements/tuntap_requirement.rb b/Library/Homebrew/requirements/tuntap_requirement.rb
index 80b842977d..6f9cec4cfd 100644
--- a/Library/Homebrew/requirements/tuntap_requirement.rb
+++ b/Library/Homebrew/requirements/tuntap_requirement.rb
@@ -2,6 +2,9 @@
 
 require "requirement"
 
+# A requirement on TunTap for macOS.
+#
+# @api private
 class TuntapRequirement < Requirement
   fatal true
   cask "tuntap"

From 481eb098c2e40dbc8df67eb62b57b3b77b1ed9b0 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 06:51:40 +0200
Subject: [PATCH 054/111] Document `X11Requirement`.

---
 Library/Homebrew/requirements/x11_requirement.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/requirements/x11_requirement.rb b/Library/Homebrew/requirements/x11_requirement.rb
index 58ecf33cf4..f34834c2ff 100644
--- a/Library/Homebrew/requirements/x11_requirement.rb
+++ b/Library/Homebrew/requirements/x11_requirement.rb
@@ -2,6 +2,9 @@
 
 require "requirement"
 
+# A requirement on X11.
+#
+# @api private
 class X11Requirement < Requirement
   include Comparable
 

From a9c271ddba582245be862095fe71b0eaf77067be Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 06:51:52 +0200
Subject: [PATCH 055/111] Document `XcodeRequirement`.

---
 Library/Homebrew/requirements/xcode_requirement.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/requirements/xcode_requirement.rb b/Library/Homebrew/requirements/xcode_requirement.rb
index 974de5f67d..97e1dde8da 100644
--- a/Library/Homebrew/requirements/xcode_requirement.rb
+++ b/Library/Homebrew/requirements/xcode_requirement.rb
@@ -2,6 +2,9 @@
 
 require "requirement"
 
+# A requirement on Xcode.
+#
+# @api private
 class XcodeRequirement < Requirement
   fatal true
 

From 7e7e4c179b910db5b100b7dc822edba7dd607599 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 06:58:36 +0200
Subject: [PATCH 056/111] Document `Resource`.

---
 Library/Homebrew/resource.rb | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Library/Homebrew/resource.rb b/Library/Homebrew/resource.rb
index e498069eae..f4753914e0 100644
--- a/Library/Homebrew/resource.rb
+++ b/Library/Homebrew/resource.rb
@@ -8,6 +8,8 @@ require "mktemp"
 # Resource is the fundamental representation of an external resource. The
 # primary formula download, along with other declared resources, are instances
 # of this class.
+#
+# @api private
 class Resource
   include Context
   include FileUtils
@@ -69,9 +71,11 @@ class Resource
   end
 
   # Verifies download and unpacks it.
-  # The block may call `|resource,staging| staging.retain!` to retain the staging
+  # The block may call `|resource, staging| staging.retain!` to retain the staging
   # directory. Subclasses that override stage should implement the tmp
   # dir using {Mktemp} so that works with all subtypes.
+  #
+  # @api public
   def stage(target = nil, &block)
     raise ArgumentError, "target directory or block is required" if !target && block.blank?
 
@@ -211,12 +215,14 @@ class Resource
     end
   end
 
+  # A resource containing a Go package.
   class Go < Resource
     def stage(target)
       super(target/name)
     end
   end
 
+  # A resource containing a patch.
   class PatchResource < Resource
     attr_reader :patch_files
 
@@ -243,6 +249,8 @@ end
 # The context in which a {Resource.stage} occurs. Supports access to both
 # the {Resource} and associated {Mktemp} in a single block argument. The interface
 # is back-compatible with {Resource} itself as used in that context.
+#
+# @api private
 class ResourceStageContext
   extend Forwardable
 

From 70cfb52158fbfa0769b4c41a3efbfb09f61d89ef Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 07:02:01 +0200
Subject: [PATCH 057/111] Document `Sandbox`.

---
 Library/Homebrew/sandbox.rb | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Library/Homebrew/sandbox.rb b/Library/Homebrew/sandbox.rb
index d50ec020f1..a0ab6c2141 100644
--- a/Library/Homebrew/sandbox.rb
+++ b/Library/Homebrew/sandbox.rb
@@ -3,8 +3,12 @@
 require "erb"
 require "tempfile"
 
+# Helper class for running a sub-process inside of a sandboxed environment.
+#
+# @api private
 class Sandbox
   SANDBOX_EXEC = "/usr/bin/sandbox-exec"
+  private_constant :SANDBOX_EXEC
 
   def self.available?
     OS.mac? && File.executable?(SANDBOX_EXEC)
@@ -139,6 +143,7 @@ class Sandbox
     end
   end
 
+  # Configuration profile for a sandbox.
   class SandboxProfile
     SEATBELT_ERB = <<~ERB
       (version 1)
@@ -181,4 +186,5 @@ class Sandbox
       ERB.new(SEATBELT_ERB).result(binding)
     end
   end
+  private_constant :SandboxProfile
 end

From 4718b8e43461393823baae9ed879c0afcf5a945b Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 07:02:45 +0200
Subject: [PATCH 058/111] Document `Search`.

---
 Library/Homebrew/search.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/search.rb b/Library/Homebrew/search.rb
index 7bfb9edba3..29fe98e8c2 100644
--- a/Library/Homebrew/search.rb
+++ b/Library/Homebrew/search.rb
@@ -4,6 +4,9 @@ require "searchable"
 require "description_cache_store"
 
 module Homebrew
+  # Helper module for searching formulae or casks.
+  #
+  # @api private
   module Search
     def query_regexp(query)
       if m = query.match(%r{^/(.*)/$})

From 735b744369b7fab4d26ddb15be889dfc855091ce Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 07:07:29 +0200
Subject: [PATCH 059/111] Document `Searchable`.

---
 Library/Homebrew/searchable.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/searchable.rb b/Library/Homebrew/searchable.rb
index 43fa35241d..9b9adc7606 100644
--- a/Library/Homebrew/searchable.rb
+++ b/Library/Homebrew/searchable.rb
@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Helper module for making a class searchable with both regular expressions and strings.
+#
+# @api private
 module Searchable
   def search(string_or_regex, &block)
     case string_or_regex

From 6bd3dbe00195ae421244e9a86711b0151e0968ea Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 07:26:09 +0200
Subject: [PATCH 060/111] Document `Style`.

---
 Library/Homebrew/style.rb | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Library/Homebrew/style.rb b/Library/Homebrew/style.rb
index be40a4dd41..36f538b158 100644
--- a/Library/Homebrew/style.rb
+++ b/Library/Homebrew/style.rb
@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Homebrew
+  # Helper module for running RuboCop.
+  #
+  # @api private
   module Style
     module_function
 
@@ -127,6 +130,7 @@ module Homebrew
       rubocop_success && shellcheck_success
     end
 
+    # Result of a RuboCop run.
     class RubocopResults
       def initialize(json)
         @metadata = json["metadata"]
@@ -144,6 +148,7 @@ module Homebrew
       end
     end
 
+    # A RuboCop offense.
     class RubocopOffense
       attr_reader :severity, :message, :corrected, :location, :cop_name
 
@@ -177,6 +182,7 @@ module Homebrew
       end
     end
 
+    # Source location of a RuboCop offense.
     class RubocopLineLocation
       attr_reader :line, :column, :length
 

From d7be7d038ab4ffb3af4e8f32334b313f6878049c Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 07:33:07 +0200
Subject: [PATCH 061/111] Document `SystemCommand`.

---
 Library/Homebrew/system_command.rb | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Library/Homebrew/system_command.rb b/Library/Homebrew/system_command.rb
index b507ec1434..05c4cb86c2 100644
--- a/Library/Homebrew/system_command.rb
+++ b/Library/Homebrew/system_command.rb
@@ -9,6 +9,9 @@ require "extend/io"
 require "extend/hash_validator"
 using HashValidator
 
+# Make `system_command` available everywhere.
+#
+# @api private
 module Kernel
   def system_command(*args)
     SystemCommand.run(*args)
@@ -19,6 +22,9 @@ module Kernel
   end
 end
 
+# Class for running sub-processes and capturing their output and exit status.
+#
+# @api private
 class SystemCommand
   include Context
   extend Predicable
@@ -167,6 +173,7 @@ class SystemCommand
     sources.each(&:close_read)
   end
 
+  # Result containing the output and exit status of a finished sub-process.
   class Result
     include Context
 

From fd3225c89c764fa9ebbbd5069a7474a9507a043b Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 07:43:40 +0200
Subject: [PATCH 062/111] Document `Analytics`.

---
 Library/Homebrew/utils/analytics.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/utils/analytics.rb b/Library/Homebrew/utils/analytics.rb
index 8f0e7e0e4d..9f0ce48c7c 100644
--- a/Library/Homebrew/utils/analytics.rb
+++ b/Library/Homebrew/utils/analytics.rb
@@ -3,6 +3,9 @@
 require "erb"
 
 module Utils
+  # Helper module for fetching and reporting analytics data.
+  #
+  # @api private
   module Analytics
     class << self
       include Context

From 843f2a19e4b53b1a115ce656e7b2b4fdd5768375 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 07:58:25 +0200
Subject: [PATCH 063/111] Document `Formatter`.

---
 Library/Homebrew/utils/formatter.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/utils/formatter.rb b/Library/Homebrew/utils/formatter.rb
index 61cdc06b87..60e88c60e1 100644
--- a/Library/Homebrew/utils/formatter.rb
+++ b/Library/Homebrew/utils/formatter.rb
@@ -2,6 +2,9 @@
 
 require "utils/tty"
 
+# Helper module for formatting output.
+#
+# @api private
 module Formatter
   module_function
 

From 6e6e01a71f795f6e400ff6c51e3f64799c16835c Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 08:10:43 +0200
Subject: [PATCH 064/111] Document `GitHub`.

---
 Library/Homebrew/utils/github.rb | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Library/Homebrew/utils/github.rb b/Library/Homebrew/utils/github.rb
index c04289fcbe..afb40bac3e 100644
--- a/Library/Homebrew/utils/github.rb
+++ b/Library/Homebrew/utils/github.rb
@@ -3,6 +3,9 @@
 require "tempfile"
 require "uri"
 
+# Helper functions for interacting with the GitHub API.
+#
+# @api private
 module GitHub
   module_function
 
@@ -15,10 +18,12 @@ module GitHub
     "https://github.com/settings/tokens/new?scopes=#{ALL_SCOPES.join(",")}&description=Homebrew",
   ).freeze
 
+  # Generic API error.
   class Error < RuntimeError
     attr_reader :github_message
   end
 
+  # Error when the requested URL is not found.
   class HTTPNotFoundError < Error
     def initialize(github_message)
       @github_message = github_message
@@ -26,6 +31,7 @@ module GitHub
     end
   end
 
+  # Error when the API rate limit is exceeded.
   class RateLimitExceededError < Error
     def initialize(reset, github_message)
       @github_message = github_message
@@ -42,6 +48,7 @@ module GitHub
     end
   end
 
+  # Error when authentication fails.
   class AuthenticationFailedError < Error
     def initialize(github_message)
       @github_message = github_message
@@ -65,6 +72,7 @@ module GitHub
     end
   end
 
+  # Error when the API returns a validation error.
   class ValidationFailedError < Error
     def initialize(github_message, errors)
       @github_message = if errors.empty?

From a3065080c336b104f678cdc233bac7cc1f7309e8 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 08:18:57 +0200
Subject: [PATCH 065/111] Document `Link`.

---
 Library/Homebrew/utils/link.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/utils/link.rb b/Library/Homebrew/utils/link.rb
index 7c24b13b1d..8b3c6bb37e 100644
--- a/Library/Homebrew/utils/link.rb
+++ b/Library/Homebrew/utils/link.rb
@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Utils
+  # Helper functions for creating symlinks.
+  #
+  # @api private
   module Link
     module_function
 

From 5426e47579612585e0599809b6be4707bb1f7882 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 19 Aug 2020 10:23:41 +0200
Subject: [PATCH 066/111] Document `Artifact`.

---
 Library/Homebrew/cask/artifact.rb                       | 3 +++
 Library/Homebrew/cask/artifact/abstract_artifact.rb     | 3 +++
 Library/Homebrew/cask/artifact/abstract_flight_block.rb | 3 +++
 Library/Homebrew/cask/artifact/abstract_uninstall.rb    | 3 +++
 Library/Homebrew/cask/artifact/app.rb                   | 3 +++
 Library/Homebrew/cask/artifact/artifact.rb              | 3 +++
 Library/Homebrew/cask/artifact/audio_unit_plugin.rb     | 3 +++
 Library/Homebrew/cask/artifact/binary.rb                | 3 +++
 Library/Homebrew/cask/artifact/colorpicker.rb           | 3 +++
 Library/Homebrew/cask/artifact/dictionary.rb            | 3 +++
 Library/Homebrew/cask/artifact/font.rb                  | 3 +++
 Library/Homebrew/cask/artifact/input_method.rb          | 3 +++
 Library/Homebrew/cask/artifact/installer.rb             | 5 +++++
 Library/Homebrew/cask/artifact/internet_plugin.rb       | 3 +++
 Library/Homebrew/cask/artifact/manpage.rb               | 3 +++
 Library/Homebrew/cask/artifact/mdimporter.rb            | 3 +++
 Library/Homebrew/cask/artifact/moved.rb                 | 3 +++
 Library/Homebrew/cask/artifact/pkg.rb                   | 3 +++
 Library/Homebrew/cask/artifact/postflight_block.rb      | 3 +++
 Library/Homebrew/cask/artifact/preflight_block.rb       | 3 +++
 Library/Homebrew/cask/artifact/prefpane.rb              | 3 +++
 Library/Homebrew/cask/artifact/qlplugin.rb              | 3 +++
 Library/Homebrew/cask/artifact/relocated.rb             | 3 +++
 Library/Homebrew/cask/artifact/screen_saver.rb          | 3 +++
 Library/Homebrew/cask/artifact/service.rb               | 3 +++
 Library/Homebrew/cask/artifact/stage_only.rb            | 3 +++
 Library/Homebrew/cask/artifact/suite.rb                 | 3 +++
 Library/Homebrew/cask/artifact/symlinked.rb             | 3 +++
 Library/Homebrew/cask/artifact/uninstall.rb             | 3 +++
 Library/Homebrew/cask/artifact/vst3_plugin.rb           | 3 +++
 Library/Homebrew/cask/artifact/vst_plugin.rb            | 3 +++
 Library/Homebrew/cask/artifact/zap.rb                   | 3 +++
 32 files changed, 98 insertions(+)

diff --git a/Library/Homebrew/cask/artifact.rb b/Library/Homebrew/cask/artifact.rb
index 6b5ca20d20..a86b3232ed 100644
--- a/Library/Homebrew/cask/artifact.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/abstract_artifact.rb b/Library/Homebrew/cask/artifact/abstract_artifact.rb
index 4d3f86d85a..84275ec58a 100644
--- a/Library/Homebrew/cask/artifact/abstract_artifact.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/abstract_flight_block.rb b/Library/Homebrew/cask/artifact/abstract_flight_block.rb
index 3eb47fe82f..053294e7ff 100644
--- a/Library/Homebrew/cask/artifact/abstract_flight_block.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/abstract_uninstall.rb b/Library/Homebrew/cask/artifact/abstract_uninstall.rb
index 272404635c..e6d17348d5 100644
--- a/Library/Homebrew/cask/artifact/abstract_uninstall.rb
+++ b/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,
diff --git a/Library/Homebrew/cask/artifact/app.rb b/Library/Homebrew/cask/artifact/app.rb
index 99bf5fcbb5..01cbec77f4 100644
--- a/Library/Homebrew/cask/artifact/app.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/artifact.rb b/Library/Homebrew/cask/artifact/artifact.rb
index 1252f40f03..3d81ab65b0 100644
--- a/Library/Homebrew/cask/artifact/artifact.rb
+++ b/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"
diff --git a/Library/Homebrew/cask/artifact/audio_unit_plugin.rb b/Library/Homebrew/cask/artifact/audio_unit_plugin.rb
index b027d294d3..c22c132d46 100644
--- a/Library/Homebrew/cask/artifact/audio_unit_plugin.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/binary.rb b/Library/Homebrew/cask/artifact/binary.rb
index 39c525762e..a1f817ca7e 100644
--- a/Library/Homebrew/cask/artifact/binary.rb
+++ b/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)
diff --git a/Library/Homebrew/cask/artifact/colorpicker.rb b/Library/Homebrew/cask/artifact/colorpicker.rb
index 627260c333..48b2452455 100644
--- a/Library/Homebrew/cask/artifact/colorpicker.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/dictionary.rb b/Library/Homebrew/cask/artifact/dictionary.rb
index fe2c2b65b1..03fded17ff 100644
--- a/Library/Homebrew/cask/artifact/dictionary.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/font.rb b/Library/Homebrew/cask/artifact/font.rb
index 3f9f385189..164731c166 100644
--- a/Library/Homebrew/cask/artifact/font.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/input_method.rb b/Library/Homebrew/cask/artifact/input_method.rb
index 8024951844..9cd6b36239 100644
--- a/Library/Homebrew/cask/artifact/input_method.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/installer.rb b/Library/Homebrew/cask/artifact/installer.rb
index e1be5f5054..7ec14f611e 100644
--- a/Library/Homebrew/cask/artifact/installer.rb
+++ b/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}'"
diff --git a/Library/Homebrew/cask/artifact/internet_plugin.rb b/Library/Homebrew/cask/artifact/internet_plugin.rb
index 21dd0b37f1..6e22874a46 100644
--- a/Library/Homebrew/cask/artifact/internet_plugin.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/manpage.rb b/Library/Homebrew/cask/artifact/manpage.rb
index 942a83c438..66453f2dba 100644
--- a/Library/Homebrew/cask/artifact/manpage.rb
+++ b/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
 
diff --git a/Library/Homebrew/cask/artifact/mdimporter.rb b/Library/Homebrew/cask/artifact/mdimporter.rb
index ab4a3527bf..c11cb9cc4b 100644
--- a/Library/Homebrew/cask/artifact/mdimporter.rb
+++ b/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"
diff --git a/Library/Homebrew/cask/artifact/moved.rb b/Library/Homebrew/cask/artifact/moved.rb
index 7774bff8ec..5925b86f4b 100644
--- a/Library/Homebrew/cask/artifact/moved.rb
+++ b/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"
diff --git a/Library/Homebrew/cask/artifact/pkg.rb b/Library/Homebrew/cask/artifact/pkg.rb
index 075de456e1..c70f2658dc 100644
--- a/Library/Homebrew/cask/artifact/pkg.rb
+++ b/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
 
diff --git a/Library/Homebrew/cask/artifact/postflight_block.rb b/Library/Homebrew/cask/artifact/postflight_block.rb
index 43cb49f5bd..c672057d8c 100644
--- a/Library/Homebrew/cask/artifact/postflight_block.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/preflight_block.rb b/Library/Homebrew/cask/artifact/preflight_block.rb
index 341cdb1e0f..f6f8882c71 100644
--- a/Library/Homebrew/cask/artifact/preflight_block.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/prefpane.rb b/Library/Homebrew/cask/artifact/prefpane.rb
index 393d6e5c4a..8447c67c1d 100644
--- a/Library/Homebrew/cask/artifact/prefpane.rb
+++ b/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"
diff --git a/Library/Homebrew/cask/artifact/qlplugin.rb b/Library/Homebrew/cask/artifact/qlplugin.rb
index b9c5f8f069..30588c6236 100644
--- a/Library/Homebrew/cask/artifact/qlplugin.rb
+++ b/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"
diff --git a/Library/Homebrew/cask/artifact/relocated.rb b/Library/Homebrew/cask/artifact/relocated.rb
index 81e47f73c9..3f0da05eb0 100644
--- a/Library/Homebrew/cask/artifact/relocated.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/screen_saver.rb b/Library/Homebrew/cask/artifact/screen_saver.rb
index ba30416256..f8f73e7021 100644
--- a/Library/Homebrew/cask/artifact/screen_saver.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/service.rb b/Library/Homebrew/cask/artifact/service.rb
index b42d22c43e..9a92a6506f 100644
--- a/Library/Homebrew/cask/artifact/service.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/stage_only.rb b/Library/Homebrew/cask/artifact/stage_only.rb
index 77ae227075..78efa24d5d 100644
--- a/Library/Homebrew/cask/artifact/stage_only.rb
+++ b/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]
diff --git a/Library/Homebrew/cask/artifact/suite.rb b/Library/Homebrew/cask/artifact/suite.rb
index 4d8332f709..be8f348205 100644
--- a/Library/Homebrew/cask/artifact/suite.rb
+++ b/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"
diff --git a/Library/Homebrew/cask/artifact/symlinked.rb b/Library/Homebrew/cask/artifact/symlinked.rb
index b50c104dc4..fd40619fad 100644
--- a/Library/Homebrew/cask/artifact/symlinked.rb
+++ b/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"
diff --git a/Library/Homebrew/cask/artifact/uninstall.rb b/Library/Homebrew/cask/artifact/uninstall.rb
index cdd2da2b86..00b385e647 100644
--- a/Library/Homebrew/cask/artifact/uninstall.rb
+++ b/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 }
diff --git a/Library/Homebrew/cask/artifact/vst3_plugin.rb b/Library/Homebrew/cask/artifact/vst3_plugin.rb
index ea5dc05d05..e82690d84b 100644
--- a/Library/Homebrew/cask/artifact/vst3_plugin.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/vst_plugin.rb b/Library/Homebrew/cask/artifact/vst_plugin.rb
index 6796e286ca..058ea50521 100644
--- a/Library/Homebrew/cask/artifact/vst_plugin.rb
+++ b/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
diff --git a/Library/Homebrew/cask/artifact/zap.rb b/Library/Homebrew/cask/artifact/zap.rb
index cd1ccc736d..6967f922c7 100644
--- a/Library/Homebrew/cask/artifact/zap.rb
+++ b/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)

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 067/111] 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

From d6003abdecddd3e52f1ba52f3bd290d331d52cdd Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 21:32:40 +0200
Subject: [PATCH 068/111] Document `Audit`.

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

diff --git a/Library/Homebrew/cask/audit.rb b/Library/Homebrew/cask/audit.rb
index f5cd9c2315..70f5d364cc 100644
--- a/Library/Homebrew/cask/audit.rb
+++ b/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
 

From 55206bdc5614685c97caa5720dce23934b53007c Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 21:33:45 +0200
Subject: [PATCH 069/111] Document `Auditor`.

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

diff --git a/Library/Homebrew/cask/auditor.rb b/Library/Homebrew/cask/auditor.rb
index cc31909c8f..9aa4820a56 100644
--- a/Library/Homebrew/cask/auditor.rb
+++ b/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
 

From a87b7115641e9ce7b85a66925cad04f7901a178d Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 21:47:07 +0200
Subject: [PATCH 070/111] Document `Cache`.

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

diff --git a/Library/Homebrew/cask/cache.rb b/Library/Homebrew/cask/cache.rb
index 2286398620..2d1dcc5706 100644
--- a/Library/Homebrew/cask/cache.rb
+++ b/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
 

From f54f3ba96da915a663736abbb7b233ae36325fbb Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 22:50:21 +0200
Subject: [PATCH 071/111] Document `Cask`.

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

diff --git a/Library/Homebrew/cask/cask.rb b/Library/Homebrew/cask/cask.rb
index 93301a0958..c04105c18a 100644
--- a/Library/Homebrew/cask/cask.rb
+++ b/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

From 5c47f531a0adfd8e23dc048338cbf727438fa156 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 22:50:29 +0200
Subject: [PATCH 072/111] Document `CaskLoader`.

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

diff --git a/Library/Homebrew/cask/cask_loader.rb b/Library/Homebrew/cask/cask_loader.rb
index 3ffd79761b..0917bbbd3a 100644
--- a/Library/Homebrew/cask/cask_loader.rb
+++ b/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

From e7f30c5b80c7a79c2e56629a73ab315b9f86f2f3 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 22:50:38 +0200
Subject: [PATCH 073/111] Document `Caskroom`.

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

diff --git a/Library/Homebrew/cask/caskroom.rb b/Library/Homebrew/cask/caskroom.rb
index 542ea0bcad..e3519440bb 100644
--- a/Library/Homebrew/cask/caskroom.rb
+++ b/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
 

From 90ade8899609b874aa9b38de5d188c87f27351fe Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 22:51:23 +0200
Subject: [PATCH 074/111] Document `Config`.

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

diff --git a/Library/Homebrew/cask/config.rb b/Library/Homebrew/cask/config.rb
index ebfe171701..2583478cce 100644
--- a/Library/Homebrew/cask/config.rb
+++ b/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",

From 7cc67ddb1b4a5a4ed4375f682dad9ef30b7fc6f0 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 22:52:16 +0200
Subject: [PATCH 075/111] Document `Denylist`.

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

diff --git a/Library/Homebrew/cask/denylist.rb b/Library/Homebrew/cask/denylist.rb
index 86bd1151ae..dda4326ba6 100644
--- a/Library/Homebrew/cask/denylist.rb
+++ b/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

From 867cc31bae5b494212bba890ab0402e50cfa36e9 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 22:53:08 +0200
Subject: [PATCH 076/111] Document `Download`.

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

diff --git a/Library/Homebrew/cask/download.rb b/Library/Homebrew/cask/download.rb
index 4bd4e4426a..16c1dbd81c 100644
--- a/Library/Homebrew/cask/download.rb
+++ b/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
 

From 5d6c682f819d07767311a4b3366e6d2f7f40c3f4 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:09:43 +0200
Subject: [PATCH 077/111] Document `Cask::DSL`.

---
 Library/Homebrew/cask/dsl.rb                   |  3 +++
 Library/Homebrew/cask/dsl/appcast.rb           |  3 +++
 Library/Homebrew/cask/dsl/base.rb              |  3 +++
 Library/Homebrew/cask/dsl/caveats.rb           | 18 +++++++++++-------
 Library/Homebrew/cask/dsl/conflicts_with.rb    |  3 +++
 Library/Homebrew/cask/dsl/container.rb         |  3 +++
 Library/Homebrew/cask/dsl/depends_on.rb        |  3 +++
 Library/Homebrew/cask/dsl/postflight.rb        |  3 +++
 Library/Homebrew/cask/dsl/preflight.rb         |  3 +++
 .../Homebrew/cask/dsl/uninstall_postflight.rb  |  3 +++
 .../Homebrew/cask/dsl/uninstall_preflight.rb   |  3 +++
 Library/Homebrew/cask/dsl/version.rb           |  3 +++
 12 files changed, 44 insertions(+), 7 deletions(-)

diff --git a/Library/Homebrew/cask/dsl.rb b/Library/Homebrew/cask/dsl.rb
index 98dd27a843..cc8f451d98 100644
--- a/Library/Homebrew/cask/dsl.rb
+++ b/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,
diff --git a/Library/Homebrew/cask/dsl/appcast.rb b/Library/Homebrew/cask/dsl/appcast.rb
index 99821e6ddd..1c9ebc3600 100644
--- a/Library/Homebrew/cask/dsl/appcast.rb
+++ b/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
 
diff --git a/Library/Homebrew/cask/dsl/base.rb b/Library/Homebrew/cask/dsl/base.rb
index bc9440de6f..4ea58e01e9 100644
--- a/Library/Homebrew/cask/dsl/base.rb
+++ b/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
 
diff --git a/Library/Homebrew/cask/dsl/caveats.rb b/Library/Homebrew/cask/dsl/caveats.rb
index b6105915e4..d9933d992c 100644
--- a/Library/Homebrew/cask/dsl/caveats.rb
+++ b/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)
diff --git a/Library/Homebrew/cask/dsl/conflicts_with.rb b/Library/Homebrew/cask/dsl/conflicts_with.rb
index d90ecdb06e..d5de4edeb9 100644
--- a/Library/Homebrew/cask/dsl/conflicts_with.rb
+++ b/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,
diff --git a/Library/Homebrew/cask/dsl/container.rb b/Library/Homebrew/cask/dsl/container.rb
index 1d8a0dbc16..60cfbdb44e 100644
--- a/Library/Homebrew/cask/dsl/container.rb
+++ b/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,
diff --git a/Library/Homebrew/cask/dsl/depends_on.rb b/Library/Homebrew/cask/dsl/depends_on.rb
index 257ff39783..b8f701ab11 100644
--- a/Library/Homebrew/cask/dsl/depends_on.rb
+++ b/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,
diff --git a/Library/Homebrew/cask/dsl/postflight.rb b/Library/Homebrew/cask/dsl/postflight.rb
index 9e0b1f55b6..cccfac6c9e 100644
--- a/Library/Homebrew/cask/dsl/postflight.rb
+++ b/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
 
diff --git a/Library/Homebrew/cask/dsl/preflight.rb b/Library/Homebrew/cask/dsl/preflight.rb
index 1cf1e03b56..eba210668d 100644
--- a/Library/Homebrew/cask/dsl/preflight.rb
+++ b/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
diff --git a/Library/Homebrew/cask/dsl/uninstall_postflight.rb b/Library/Homebrew/cask/dsl/uninstall_postflight.rb
index db83749a22..fac89d764e 100644
--- a/Library/Homebrew/cask/dsl/uninstall_postflight.rb
+++ b/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
diff --git a/Library/Homebrew/cask/dsl/uninstall_preflight.rb b/Library/Homebrew/cask/dsl/uninstall_preflight.rb
index 25d8f1d0d5..770fc680a3 100644
--- a/Library/Homebrew/cask/dsl/uninstall_preflight.rb
+++ b/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
diff --git a/Library/Homebrew/cask/dsl/version.rb b/Library/Homebrew/cask/dsl/version.rb
index fd8328ad06..53d58b9961 100644
--- a/Library/Homebrew/cask/dsl/version.rb
+++ b/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,

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 078/111] 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."

From 5f152f5dc3c18c46eb42c10467fbf7aae7d858e5 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:33:12 +0200
Subject: [PATCH 079/111] Document `Installer`.

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

diff --git a/Library/Homebrew/cask/installer.rb b/Library/Homebrew/cask/installer.rb
index 5ad75d01ce..e28e4fa093 100644
--- a/Library/Homebrew/cask/installer.rb
+++ b/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

From be019cdb3b22e0500c040834f1a0ae5c074e17eb Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:41:50 +0200
Subject: [PATCH 080/111] Document `Metadata`.

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

diff --git a/Library/Homebrew/cask/metadata.rb b/Library/Homebrew/cask/metadata.rb
index b15fbdda39..8c12de10bb 100644
--- a/Library/Homebrew/cask/metadata.rb
+++ b/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"

From b484ddc8424ab2f1fffcb6848796a9db457b7445 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:43:40 +0200
Subject: [PATCH 081/111] Document `Pkg`.

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

diff --git a/Library/Homebrew/cask/pkg.rb b/Library/Homebrew/cask/pkg.rb
index f6c4a2444f..f015ee9de8 100644
--- a/Library/Homebrew/cask/pkg.rb
+++ b/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|

From ad74b96dd8551c4b24d9b45ed59cc8447d2fb6d8 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:44:12 +0200
Subject: [PATCH 082/111] Document `Quarantine`.

---
 Library/Homebrew/cask/quarantine.rb | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Library/Homebrew/cask/quarantine.rb b/Library/Homebrew/cask/quarantine.rb
index 381ee80a06..a90a7ea942 100644
--- a/Library/Homebrew/cask/quarantine.rb
+++ b/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"

From 32f5c00be1388121f3c6259cf6edcbd8250d683d Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:49:10 +0200
Subject: [PATCH 083/111] Document `TopologicalHash`.

---
 Library/Homebrew/cask/topological_hash.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Library/Homebrew/cask/topological_hash.rb b/Library/Homebrew/cask/topological_hash.rb
index 919dc161f7..bfd8573827 100644
--- a/Library/Homebrew/cask/topological_hash.rb
+++ b/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
 

From 258a579feeefe6fa204fad429aae070741437fc4 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:49:46 +0200
Subject: [PATCH 084/111] Make `cask/macos` constants private.

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

diff --git a/Library/Homebrew/cask/macos.rb b/Library/Homebrew/cask/macos.rb
index 49e34caed8..cf65def619 100644
--- a/Library/Homebrew/cask/macos.rb
+++ b/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)

From 7e3aee2669585122dabd5de8dfcc1a5879e0e1f6 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:50:47 +0200
Subject: [PATCH 085/111] Document `Staged`.

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

diff --git a/Library/Homebrew/cask/staged.rb b/Library/Homebrew/cask/staged.rb
index b0216fc344..73dd826e9a 100644
--- a/Library/Homebrew/cask/staged.rb
+++ b/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)

From b92f3a2e937aad2a6195508e423116baecf814ae Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:51:48 +0200
Subject: [PATCH 086/111] Document `URL`.

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

diff --git a/Library/Homebrew/cask/url.rb b/Library/Homebrew/cask/url.rb
index ad7c3506e7..2e59372f9d 100644
--- a/Library/Homebrew/cask/url.rb
+++ b/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
 

From d9c1f6cf2dd378f2d9446b5dcf30c86cbddd180c Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Mon, 24 Aug 2020 23:54:41 +0200
Subject: [PATCH 087/111] Document `Utils`.

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

diff --git a/Library/Homebrew/cask/utils.rb b/Library/Homebrew/cask/utils.rb
index a4b521bc2e..8cee597600 100644
--- a/Library/Homebrew/cask/utils.rb
+++ b/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?

From 2484ddb56507047f01e7460e5ce40dc3172101d2 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 25 Aug 2020 00:00:50 +0200
Subject: [PATCH 088/111] Document `Verify`.

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

diff --git a/Library/Homebrew/cask/verify.rb b/Library/Homebrew/cask/verify.rb
index ca0c0ddeea..f31d234c42 100644
--- a/Library/Homebrew/cask/verify.rb
+++ b/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
 

From dbfc6dc7a5374ffbb1f895df182501e7d931eda5 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 25 Aug 2020 00:01:15 +0200
Subject: [PATCH 089/111] Document `OS`.

---
 Library/Homebrew/os.rb | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Library/Homebrew/os.rb b/Library/Homebrew/os.rb
index ff739cd20f..4981f12b53 100644
--- a/Library/Homebrew/os.rb
+++ b/Library/Homebrew/os.rb
@@ -1,18 +1,30 @@
 # frozen_string_literal: true
 
+# Helper functions for querying operating system information.
+#
+# @api private
 module OS
+  # Check if the operating system is macOS.
+  #
+  # @api public
   def self.mac?
     return false if ENV["HOMEBREW_TEST_GENERIC_OS"]
 
     RbConfig::CONFIG["host_os"].include? "darwin"
   end
 
+  # Check if the operating system is Linux.
+  #
+  # @api public
   def self.linux?
     return false if ENV["HOMEBREW_TEST_GENERIC_OS"]
 
     RbConfig::CONFIG["host_os"].include? "linux"
   end
 
+  # Get the kernel version.
+  #
+  # @api public
   def self.kernel_version
     @kernel_version ||= Version.new(Utils.safe_popen_read("uname", "-r").chomp)
   end

From 4304fa048e4ed69cfa857a8251fca24cf519fc85 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 25 Aug 2020 00:11:59 +0200
Subject: [PATCH 090/111] Document `ELFShim`.

---
 Library/Homebrew/os/linux/elf.rb | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/Library/Homebrew/os/linux/elf.rb b/Library/Homebrew/os/linux/elf.rb
index 05ebff0c3c..a0d84e7d4f 100644
--- a/Library/Homebrew/os/linux/elf.rb
+++ b/Library/Homebrew/os/linux/elf.rb
@@ -1,24 +1,42 @@
 # frozen_string_literal: true
 
+# {Pathname} extension for dealing with ELF files.
+#
 # @see https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header
+#
+# @api private
 module ELFShim
   MAGIC_NUMBER_OFFSET = 0
+  private_constant :MAGIC_NUMBER_OFFSET
   MAGIC_NUMBER_ASCII = "\x7fELF"
+  private_constant :MAGIC_NUMBER_ASCII
 
   OS_ABI_OFFSET = 0x07
+  private_constant :OS_ABI_OFFSET
   OS_ABI_SYSTEM_V = 0
+  private_constant :OS_ABI_SYSTEM_V
   OS_ABI_LINUX = 3
+  private_constant :OS_ABI_LINUX
 
   TYPE_OFFSET = 0x10
+  private_constant :TYPE_OFFSET
   TYPE_EXECUTABLE = 2
+  private_constant :TYPE_EXECUTABLE
   TYPE_SHARED = 3
+  private_constant :TYPE_SHARED
 
   ARCHITECTURE_OFFSET = 0x12
+  private_constant :ARCHITECTURE_OFFSET
   ARCHITECTURE_I386 = 0x3
+  private_constant :ARCHITECTURE_I386
   ARCHITECTURE_POWERPC = 0x14
+  private_constant :ARCHITECTURE_POWERPC
   ARCHITECTURE_ARM = 0x28
+  private_constant :ARCHITECTURE_ARM
   ARCHITECTURE_X86_64 = 0x62
+  private_constant :ARCHITECTURE_X86_64
   ARCHITECTURE_AARCH64 = 0xB7
+  private_constant :ARCHITECTURE_AARCH64
 
   def read_uint8(offset)
     read(1, offset).unpack1("C")
@@ -86,6 +104,9 @@ module ELFShim
     @dynamic_elf = patchelf_patcher.elf.segment_by_type(:DYNAMIC).present?
   end
 
+  # Helper class for reading metadata from an ELF file.
+  #
+  # @api private
   class Metadata
     attr_reader :path, :dylib_id, :dylibs
 
@@ -125,6 +146,7 @@ module ELFShim
       [patcher.soname, patcher.needed]
     end
   end
+  private_constant :Metadata
 
   def rpath_using_patchelf_rb
     patchelf_patcher.runpath || patchelf_patcher.rpath
@@ -138,6 +160,7 @@ module ELFShim
   def metadata
     @metadata ||= Metadata.new(self)
   end
+  private :metadata
 
   def dylib_id
     metadata.dylib_id

From 6f0f8bd5740d19288c3fdbe49902c52b9dbe4dce Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 25 Aug 2020 00:18:36 +0200
Subject: [PATCH 091/111] Document `Glibc`.

---
 Library/Homebrew/os/linux/glibc.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/os/linux/glibc.rb b/Library/Homebrew/os/linux/glibc.rb
index c7073b39f3..a42ee092d0 100644
--- a/Library/Homebrew/os/linux/glibc.rb
+++ b/Library/Homebrew/os/linux/glibc.rb
@@ -2,6 +2,9 @@
 
 module OS
   module Linux
+    # Helper functions for querying `glibc` information.
+    #
+    # @api private
     module Glibc
       module_function
 

From f7cb6a95b6d0b5eacb0d645d007bac4613589281 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 25 Aug 2020 00:19:57 +0200
Subject: [PATCH 092/111] Document `Kernel`.

---
 Library/Homebrew/os/linux/kernel.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/os/linux/kernel.rb b/Library/Homebrew/os/linux/kernel.rb
index 31680b9e7e..1c20ce5a14 100644
--- a/Library/Homebrew/os/linux/kernel.rb
+++ b/Library/Homebrew/os/linux/kernel.rb
@@ -2,6 +2,9 @@
 
 module OS
   module Linux
+    # Helper functions for querying Linux kernel information.
+    #
+    # @api private
     module Kernel
       module_function
 

From 390deeb5ac92b54583283b1a1f1d1162577133a7 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 25 Aug 2020 00:28:26 +0200
Subject: [PATCH 093/111] Document `MachOShim`.

---
 Library/Homebrew/os/mac/mach.rb | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Library/Homebrew/os/mac/mach.rb b/Library/Homebrew/os/mac/mach.rb
index 93cab7de4f..aef8164268 100644
--- a/Library/Homebrew/os/mac/mach.rb
+++ b/Library/Homebrew/os/mac/mach.rb
@@ -3,19 +3,21 @@
 require "macho"
 require "os/mac/architecture_list"
 
+# {Pathname} extension for dealing with Mach-O files.
+#
+# @api private
 module MachOShim
   extend Forwardable
 
   delegate [:dylib_id, :rpaths, :delete_rpath] => :macho
 
-  # @private
   def macho
     @macho ||= begin
       MachO.open(to_s)
     end
   end
+  private :macho
 
-  # @private
   def mach_data
     @mach_data ||= begin
       machos = []
@@ -55,6 +57,7 @@ module MachOShim
       []
     end
   end
+  private :mach_data
 
   def dynamically_linked_libraries(except: :none)
     lcs = macho.dylib_load_commands.reject { |lc| lc.type == except }
@@ -94,19 +97,16 @@ module MachOShim
     arch == :ppc64
   end
 
-  # @private
   def dylib?
     mach_data.any? { |m| m.fetch(:type) == :dylib }
   end
 
-  # @private
   def mach_o_executable?
     mach_data.any? { |m| m.fetch(:type) == :executable }
   end
 
   alias binary_executable? mach_o_executable?
 
-  # @private
   def mach_o_bundle?
     mach_data.any? { |m| m.fetch(:type) == :bundle }
   end

From 3efaf8978744285ffbee89db082fb32fb9805c99 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 25 Aug 2020 00:33:34 +0200
Subject: [PATCH 094/111] Document `SDK`.

---
 Library/Homebrew/os/mac/sdk.rb | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/Library/Homebrew/os/mac/sdk.rb b/Library/Homebrew/os/mac/sdk.rb
index f6061c3712..54bed4fabb 100644
--- a/Library/Homebrew/os/mac/sdk.rb
+++ b/Library/Homebrew/os/mac/sdk.rb
@@ -4,6 +4,9 @@ require "os/mac/version"
 
 module OS
   module Mac
+    # Class representing a macOS SDK.
+    #
+    # @api private
     class SDK
       attr_reader :version, :path, :source
 
@@ -14,6 +17,9 @@ module OS
       end
     end
 
+    # Base class for SDK locators.
+    #
+    # @api private
     class BaseSDKLocator
       class NoSDKError < StandardError; end
 
@@ -42,7 +48,7 @@ module OS
           else
             sdk_for v
           end
-        rescue BaseSDKLocator::NoSDKError
+        rescue NoSDKError
           latest_sdk
         end
         # Only return an SDK older than the OS version if it was specifically requested
@@ -79,7 +85,11 @@ module OS
         end
       end
     end
+    private_constant :BaseSDKLocator
 
+    # Helper class for locating the Xcode SDK.
+    #
+    # @api private
     class XcodeSDKLocator < BaseSDKLocator
       def source
         :xcode
@@ -100,6 +110,9 @@ module OS
       end
     end
 
+    # Helper class for locating the macOS Command Line Tools SDK.
+    #
+    # @api private
     class CLTSDKLocator < BaseSDKLocator
       def source
         :clt

From e3d78de5f1c4e26bac02b8c258ecc353ea190177 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 25 Aug 2020 00:35:07 +0200
Subject: [PATCH 095/111] Document `Mac::Version`.

---
 Library/Homebrew/os/mac/version.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/os/mac/version.rb b/Library/Homebrew/os/mac/version.rb
index 2134637344..1c47f9ee88 100644
--- a/Library/Homebrew/os/mac/version.rb
+++ b/Library/Homebrew/os/mac/version.rb
@@ -5,6 +5,9 @@ require "version"
 
 module OS
   module Mac
+    # A macOS version.
+    #
+    # @api private
     class Version < ::Version
       SYMBOLS = {
         big_sur:     "11.0",

From aac015113234ece3ff1161d3865ab17cb4499d28 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 25 Aug 2020 00:38:56 +0200
Subject: [PATCH 096/111] Document `Xcode`.

---
 Library/Homebrew/os/mac/xcode.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/os/mac/xcode.rb b/Library/Homebrew/os/mac/xcode.rb
index 5f1a23d663..5e9c8d6180 100644
--- a/Library/Homebrew/os/mac/xcode.rb
+++ b/Library/Homebrew/os/mac/xcode.rb
@@ -2,6 +2,9 @@
 
 module OS
   module Mac
+    # Helper module for querying Xcode information.
+    #
+    # @api private
     module Xcode
       module_function
 

From 07365b9ad033d281e0ae65795dd529301c0576e7 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 25 Aug 2020 00:40:10 +0200
Subject: [PATCH 097/111] Document `CLT`.

---
 Library/Homebrew/os/mac/xcode.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/os/mac/xcode.rb b/Library/Homebrew/os/mac/xcode.rb
index 5e9c8d6180..9aa9ba746d 100644
--- a/Library/Homebrew/os/mac/xcode.rb
+++ b/Library/Homebrew/os/mac/xcode.rb
@@ -203,6 +203,9 @@ module OS
       end
     end
 
+    # Helper module for querying macOS Command Line Tools information.
+    #
+    # @api private
     module CLT
       module_function
 

From a91e606d48dc3a11dccedad9e4b3ebae11577d0a Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:21:58 +0200
Subject: [PATCH 098/111] Document `FormulaAudit::Caveats`.

---
 Library/Homebrew/rubocops/caveats.rb | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Library/Homebrew/rubocops/caveats.rb b/Library/Homebrew/rubocops/caveats.rb
index 09233e48ea..f81c4fc26f 100644
--- a/Library/Homebrew/rubocops/caveats.rb
+++ b/Library/Homebrew/rubocops/caveats.rb
@@ -5,6 +5,24 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
+      # This cop makes sure that caveats don't recommend unsupported or unsafe operations.
+      #
+      # @example
+      #   # bad
+      #   def caveats
+      #     <<~EOS
+      #       Use `setuid` to allow running the exeutable by non-root users.
+      #     EOS
+      #   end
+      #
+      #   # good
+      #   def caveats
+      #     <<~EOS
+      #       Use `sudo` to run the executable.
+      #     EOS
+      #   end
+      #
+      # @api private
       class Caveats < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, _body_node)
           caveats_strings.each do |n|

From 924fc47f0f55c094c34b528c163b3d0a362f85e2 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:22:23 +0200
Subject: [PATCH 099/111] Document `FormulaAudit::Checksum`.

---
 Library/Homebrew/rubocops/checksum.rb | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Library/Homebrew/rubocops/checksum.rb b/Library/Homebrew/rubocops/checksum.rb
index 4feff95e1a..fda9de60d1 100644
--- a/Library/Homebrew/rubocops/checksum.rb
+++ b/Library/Homebrew/rubocops/checksum.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
+      # This cop makes sure that deprecated checksums are not used.
+      #
+      # @api private
       class Checksum < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           return if body_node.nil?
@@ -39,6 +42,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that checksums strings are lowercase.
+      #
+      # @api private
       class ChecksumCase < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           return if body_node.nil?

From 69a0e3fb6190614513b26ce08db3506f8dc404ae Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:24:22 +0200
Subject: [PATCH 100/111] Document `FormulaAudit::ComponentsRedundancy`.

---
 Library/Homebrew/rubocops/components_redundancy.rb | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Library/Homebrew/rubocops/components_redundancy.rb b/Library/Homebrew/rubocops/components_redundancy.rb
index d0d6298d50..695971e0cd 100644
--- a/Library/Homebrew/rubocops/components_redundancy.rb
+++ b/Library/Homebrew/rubocops/components_redundancy.rb
@@ -5,13 +5,14 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop checks if redundant components are present and other component errors.
+      # This cop checks if redundant components are present and for other component errors.
       #
       # - `url|checksum|mirror` should be inside `stable` block
       # - `head` and `head do` should not be simultaneously present
       # - `bottle :unneeded`/`:disable` and `bottle do` should not be simultaneously present
       # - `stable do` should not be present without a `head` or `devel` spec
-
+      #
+      # @api private
       class ComponentsRedundancy < FormulaCop
         HEAD_MSG = "`head` and `head do` should not be simultaneously present"
         BOTTLE_MSG = "`bottle :modifier` and `bottle do` should not be simultaneously present"

From 26af3b5807cac3967454e0c923546f96dae391d8 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:28:17 +0200
Subject: [PATCH 101/111] Document `rubocops/class` cops.

---
 Library/Homebrew/rubocops/class.rb | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Library/Homebrew/rubocops/class.rb b/Library/Homebrew/rubocops/class.rb
index 7fde505269..56ce23cff1 100644
--- a/Library/Homebrew/rubocops/class.rb
+++ b/Library/Homebrew/rubocops/class.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
+      # This cop makes sure that `Formula` is used as superclass.
+      #
+      # @api private
       class ClassName < FormulaCop
         DEPRECATED_CLASSES = %w[
           GithubGistFormula
@@ -26,6 +29,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that a `test` block contains a proper test.
+      #
+      # @api private
       class Test < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           test = find_block(body_node, :test)
@@ -78,7 +84,9 @@ module RuboCop
     end
 
     module FormulaAuditStrict
-      # - `test do ..end` should defined in the formula.
+      # This cop makes sure that a `test` block exists.
+      #
+      # @api private
       class TestPresent < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           return if find_block(body_node, :test)

From 7185e4c9a7782236cb529eb7391f5a780b4db552 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:31:31 +0200
Subject: [PATCH 102/111] Document `FormulaAudit::Files`.

---
 Library/Homebrew/rubocops/files.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/rubocops/files.rb b/Library/Homebrew/rubocops/files.rb
index 843972daca..d4454ad4cb 100644
--- a/Library/Homebrew/rubocops/files.rb
+++ b/Library/Homebrew/rubocops/files.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
+      # This cop makes sure that a formula's file permissions are correct.
+      #
+      # @api private
       class Files < FormulaCop
         def audit_formula(node, _class_node, _parent_class_node, _body_node)
           return unless file_path

From 8e55d7fde28a16fbf9260c8da36c2b8feb66b98b Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:33:38 +0200
Subject: [PATCH 103/111] Document `FormulaAudit::KegOnly`.

---
 Library/Homebrew/rubocops/keg_only.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/rubocops/keg_only.rb b/Library/Homebrew/rubocops/keg_only.rb
index 820bf79541..6a578b5f7c 100644
--- a/Library/Homebrew/rubocops/keg_only.rb
+++ b/Library/Homebrew/rubocops/keg_only.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
+      # This cop makes sure that a `keg_only` reason has the correct format.
+      #
+      # @api private
       class KegOnly < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           keg_only_node = find_node_method_by_name(body_node, :keg_only)

From 52efa13222eea299ef0fbae44abef391633f710a Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:50:19 +0200
Subject: [PATCH 104/111] Document `rubocops/lines` cops.

---
 Library/Homebrew/rubocops/lines.rb | 38 ++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/Library/Homebrew/rubocops/lines.rb b/Library/Homebrew/rubocops/lines.rb
index a29092b425..158a7b8c60 100644
--- a/Library/Homebrew/rubocops/lines.rb
+++ b/Library/Homebrew/rubocops/lines.rb
@@ -6,6 +6,8 @@ module RuboCop
   module Cop
     module FormulaAudit
       # This cop checks for various miscellaneous Homebrew coding styles.
+      #
+      # @api private
       class Lines < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, _body_node)
           [:automake, :ant, :autoconf, :emacs, :expat, :libtool, :mysql, :perl,
@@ -26,6 +28,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that a space is used for class inheritance.
+      #
+      # @api private
       class ClassInheritance < FormulaCop
         def audit_formula(_node, class_node, parent_class_node, _body_node)
           begin_pos = start_column(parent_class_node)
@@ -37,6 +42,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that template comments are removed.
+      #
+      # @api private
       class Comments < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, _body_node)
           audit_comments do |comment|
@@ -76,6 +84,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that idiomatic `assert_*` statements are used.
+      #
+      # @api private
       class AssertStatements < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           find_every_method_call_by_name(body_node, :assert).each do |method|
@@ -98,6 +109,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that options are used idiomatically.
+      #
+      # @api private
       class OptionDeclarations < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           problem "Use new-style option definitions" if find_method_def(body_node, :options)
@@ -178,6 +192,9 @@ module RuboCop
         EOS
       end
 
+      # This cop makes sure that formulae depend on `open-mpi` instead of `mpich`.
+      #
+      # @api private
       class MpiCheck < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           # Enforce use of OpenMPI for MPI dependency in core
@@ -197,6 +214,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that the safe versions of `popen_*` calls are used.
+      #
+      # @api private
       class SafePopenCommands < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           test = find_block(body_node, :test)
@@ -225,6 +245,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that environment variables are passed correctly to `popen_*` calls.
+      #
+      # @api private
       class ShellVariables < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           popen_commands = [
@@ -254,6 +277,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that `license` has the correct format.
+      #
+      # @api private
       class LicenseArrays < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           license_node = find_node_method_by_name(body_node, :license)
@@ -272,6 +298,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that nested `license` declarations are split onto multiple lines.
+      #
+      # @api private
       class Licenses < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           license_node = find_node_method_by_name(body_node, :license)
@@ -286,6 +315,9 @@ module RuboCop
         end
       end
 
+      # This cop checks for other miscellaneous style violations.
+      #
+      # @api private
       class Miscellaneous < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           # FileUtils is included in Formula
@@ -545,6 +577,9 @@ module RuboCop
     end
 
     module FormulaAuditStrict
+      # This cop makes sure that no build-time checks are performed.
+      #
+      # @api private
       class MakeCheck < FormulaCop
         MAKE_CHECK_ALLOWLIST = %w[
           beecrypt
@@ -588,6 +623,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that shell command arguments are separated.
+      #
+      # @api private
       class ShellCommands < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           # Match shell commands separated by spaces in the same string

From 7e2e5bf388bb1ea35cfae26b8b7911d437e0eae1 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:50:44 +0200
Subject: [PATCH 105/111] Document `FormulaCop`.

---
 Library/Homebrew/rubocops/extend/formula.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/rubocops/extend/formula.rb b/Library/Homebrew/rubocops/extend/formula.rb
index 8f165acc68..80819e92f2 100644
--- a/Library/Homebrew/rubocops/extend/formula.rb
+++ b/Library/Homebrew/rubocops/extend/formula.rb
@@ -14,6 +14,9 @@ require "rubocops/shared/helper_functions"
 
 module RuboCop
   module Cop
+    # Superclass for all formula cops.
+    #
+    # @api private
     class FormulaCop < Cop
       include RangeHelp
       include HelperFunctions

From d5ba5cb8f8bf6f3f091f5707f96c47348491c9e1 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:52:48 +0200
Subject: [PATCH 106/111] Document `rubocops/shared` modules.

---
 Library/Homebrew/rubocops/shared/desc_helper.rb      | 2 ++
 Library/Homebrew/rubocops/shared/helper_functions.rb | 3 +++
 2 files changed, 5 insertions(+)

diff --git a/Library/Homebrew/rubocops/shared/desc_helper.rb b/Library/Homebrew/rubocops/shared/desc_helper.rb
index 3ed62a036b..80092a8df7 100644
--- a/Library/Homebrew/rubocops/shared/desc_helper.rb
+++ b/Library/Homebrew/rubocops/shared/desc_helper.rb
@@ -5,6 +5,8 @@ require "rubocops/shared/helper_functions"
 module RuboCop
   module Cop
     # This module performs common checks the `desc` field in both Formulae and Casks.
+    #
+    # @api private
     module DescHelper
       include HelperFunctions
 
diff --git a/Library/Homebrew/rubocops/shared/helper_functions.rb b/Library/Homebrew/rubocops/shared/helper_functions.rb
index a5e893c6ae..8b7388f94c 100644
--- a/Library/Homebrew/rubocops/shared/helper_functions.rb
+++ b/Library/Homebrew/rubocops/shared/helper_functions.rb
@@ -2,6 +2,9 @@
 
 module RuboCop
   module Cop
+    # Helper functions for cops.
+    #
+    # @api private
     module HelperFunctions
       include RangeHelp
 

From 7719b4e1f0d1583d6ef5abee91c66c6542cc7480 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 02:59:09 +0200
Subject: [PATCH 107/111] Document `FormulaAudit::Text`.

---
 Library/Homebrew/rubocops/text.rb | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Library/Homebrew/rubocops/text.rb b/Library/Homebrew/rubocops/text.rb
index 49dece4dd4..b8fa914e4d 100644
--- a/Library/Homebrew/rubocops/text.rb
+++ b/Library/Homebrew/rubocops/text.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
+      # This cop checks for various problems in a formula's source code.
+      #
+      # @api private
       class Text < FormulaCop
         def audit_formula(node, _class_node, _parent_class_node, body_node)
           @full_source_content = source_buffer(node).source
@@ -122,6 +125,9 @@ module RuboCop
     end
 
     module FormulaAuditStrict
+      # This cop contains stricter checks for various problems in a formula's source code.
+      #
+      # @api private
       class Text < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           find_method_with_args(body_node, :go_resource) do

From 7630cee8e1df5a6d6deea3cd46010e3a5f6de37f Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 03:00:56 +0200
Subject: [PATCH 108/111] Document `FormulaAudit::Urls`.

---
 Library/Homebrew/rubocops/urls.rb | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Library/Homebrew/rubocops/urls.rb b/Library/Homebrew/rubocops/urls.rb
index 8f6a3aefda..ca6a22d1ec 100644
--- a/Library/Homebrew/rubocops/urls.rb
+++ b/Library/Homebrew/rubocops/urls.rb
@@ -6,6 +6,8 @@ module RuboCop
   module Cop
     module FormulaAudit
       # This cop audits URLs and mirrors in Formulae.
+      #
+      # @api private
       class Urls < FormulaCop
         # These are parts of URLs that look like binaries but actually aren't.
         NOT_A_BINARY_URL_PREFIX_ALLOWLIST = %w[
@@ -285,6 +287,9 @@ module RuboCop
         end
       end
 
+      # This cop makes sure that the correct format for PyPi URLs is used.
+      #
+      # @api private
       class PyPiUrls < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           urls = find_every_func_call_by_name(body_node, :url)

From c43407f40e736b0ff9fc0ca1a5373077f4a6f0f9 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 03:01:52 +0200
Subject: [PATCH 109/111] Document `FormulaAudit::Version`.

---
 Library/Homebrew/rubocops/version.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Library/Homebrew/rubocops/version.rb b/Library/Homebrew/rubocops/version.rb
index f4ed91c18d..de47a9d290 100644
--- a/Library/Homebrew/rubocops/version.rb
+++ b/Library/Homebrew/rubocops/version.rb
@@ -5,6 +5,9 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
+      # This cop makes sure that a version is in the correct format.
+      #
+      # @api private
       class Version < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           version_node = find_node_method_by_name(body_node, :version)

From 5410701eff76c5427a913151cc4227e4bb0a2000 Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Wed, 26 Aug 2020 03:06:19 +0200
Subject: [PATCH 110/111] Document `OS::Mac` and `OS::Linux`.

---
 Library/Homebrew/os/linux.rb | 4 +++-
 Library/Homebrew/os/mac.rb   | 1 +
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/Library/Homebrew/os/linux.rb b/Library/Homebrew/os/linux.rb
index da4b9d7acd..1e3cb24fa8 100644
--- a/Library/Homebrew/os/linux.rb
+++ b/Library/Homebrew/os/linux.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module OS
+  # Helper module for querying system information on Linux.
   module Linux
     module_function
 
@@ -21,7 +22,7 @@ module OS
     end
   end
 
-  # Define OS::Mac on Linux for formula API compatibility.
+  # rubocop:disable Style/Documentation
   module Mac
     module_function
 
@@ -77,4 +78,5 @@ module OS
       end
     end
   end
+  # rubocop:enable Style/Documentation
 end
diff --git a/Library/Homebrew/os/mac.rb b/Library/Homebrew/os/mac.rb
index b44a47bcc4..8e9d0d33f3 100644
--- a/Library/Homebrew/os/mac.rb
+++ b/Library/Homebrew/os/mac.rb
@@ -7,6 +7,7 @@ require "os/mac/sdk"
 require "os/mac/keg"
 
 module OS
+  # Helper module for querying system information on macOS.
   module Mac
     module_function
 

From 097ef39bab99b0a17599f8c8744bf94242826c8b Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 14 Aug 2020 01:58:14 +0200
Subject: [PATCH 111/111] Add `.rubocop_todo.yml` for documentation.

---
 Library/.rubocop_cask.yml          |  4 ++++
 Library/Homebrew/.rubocop.yml      | 19 +++++++++---------
 Library/Homebrew/.rubocop_todo.yml | 31 ++++++++++++++++++++++++++++++
 3 files changed, 45 insertions(+), 9 deletions(-)
 create mode 100644 Library/Homebrew/.rubocop_todo.yml

diff --git a/Library/.rubocop_cask.yml b/Library/.rubocop_cask.yml
index cc6ccf9a5f..e4c4939a38 100644
--- a/Library/.rubocop_cask.yml
+++ b/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
diff --git a/Library/Homebrew/.rubocop.yml b/Library/Homebrew/.rubocop.yml
index d517069b81..e280f0f62f 100644
--- a/Library/Homebrew/.rubocop.yml
+++ b/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:
diff --git a/Library/Homebrew/.rubocop_todo.yml b/Library/Homebrew/.rubocop_todo.yml
new file mode 100644
index 0000000000..a74f62002a
--- /dev/null
+++ b/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'