apidoc: update comment wording, punctuation, formatting

Library/Homebrew/cache_store.rb

@@ -4,7 +4,7 @@
 require "json"
 
 #
-# `CacheStoreDatabase` acts as an interface to a persistent storage mechanism
+# {CacheStoreDatabase} acts as an interface to a persistent storage mechanism
 # residing in the `HOMEBREW_CACHE`.
 #
 class CacheStoreDatabase
@@ -67,7 +67,7 @@ class CacheStoreDatabase
     cache_path.atomic_write(JSON.dump(@db))
   end
 
-  # Returns `true` if the cache file has been created for the given `@type`
+  # Returns `true` if the cache file has been created for the given `@type`.
   #
   # @return [Boolean]
   def created?
@@ -107,8 +107,8 @@ class CacheStoreDatabase
   private
 
   # Lazily loaded database in read/write mode. If this method is called, a
-  # database file with be created in the `HOMEBREW_CACHE` with name
-  # corresponding to the `@type` instance variable
+  # database file will be created in the `HOMEBREW_CACHE` with a name
+  # corresponding to the `@type` instance variable.
   #
   # @return [Hash] db
   def db
@@ -120,7 +120,7 @@ class CacheStoreDatabase
     @db ||= {}
   end
 
-  # Creates a CacheStoreDatabase
+  # Creates a CacheStoreDatabase.
   #
   # @param  [Symbol] type
   # @return [nil]
@@ -130,19 +130,19 @@ class CacheStoreDatabase
   end
 
   # The path where the database resides in the `HOMEBREW_CACHE` for the given
-  # `@type`
+  # `@type`.
   #
   # @return [String]
   def cache_path
     HOMEBREW_CACHE/"#{@type}.json"
   end
 
-  # Sets that the cache needs written to disk.
+  # Sets that the cache needs to be written to disk.
   def dirty!
     @dirty = true
   end
 
-  # Returns `true` if the cache needs written to disk.
+  # Returns `true` if the cache needs to be written to disk.
   #
   # @return [Boolean]
   def dirty?
@@ -151,7 +151,7 @@ class CacheStoreDatabase
 end
 
 #
-# `CacheStore` provides methods to mutate and fetch data from a persistent
+# {CacheStore} provides methods to mutate and fetch data from a persistent
 # storage mechanism.
 #
 class CacheStore
@@ -161,8 +161,7 @@ class CacheStore
     @database = database
   end
 
-  # Inserts new values or updates existing cached values to persistent storage
-  # mechanism
+  # Inserts new values or updates existing cached values to persistent storage.
   #
   # @abstract
   def update!(*)
@@ -170,14 +169,14 @@ class CacheStore
   end
 
   # Fetches cached values in persistent storage according to the type of data
-  # stored
+  # stored.
   #
   # @abstract
   def fetch(*)
     raise NotImplementedError
   end
 
-  # Deletes data from the cache based on a condition defined in a concrete class
+  # Deletes data from the cache based on a condition defined in a concrete class.
   #
   # @abstract
   def delete!(*)

Library/Homebrew/cask/artifact/abstract_uninstall.rb

@@ -79,7 +79,7 @@ module Cask
 
       # Preserve prior functionality of script which runs first. Should rarely be needed.
       # :early_script should not delete files, better defer that to :script.
-      # If Cask writers never need :early_script it may be removed in the future.
+      # If cask writers never need :early_script it may be removed in the future.
       def uninstall_early_script(directives, **options)
         uninstall_script(directives, directive_name: :early_script, **options)
       end

Library/Homebrew/cask/artifact/moved.rb

@@ -5,7 +5,7 @@ require "cask/artifact/relocated"
 
 module Cask
   module Artifact
-    # Superclass for all artifacts which are installed by moving them to the target location.
+    # Superclass for all artifacts that are installed by moving them to the target location.
     #
     # @api private
     class Moved < Relocated

Library/Homebrew/cask/cmd/internal_stanza.rb

@@ -13,7 +13,7 @@ module Cask
       #
       #     brew cask _stanza <stanza_name> [ --quiet ] [ --table | --yaml ] [ <cask_token> ... ]
       #
-      # If no tokens are given, then data for all Casks is returned.
+      # If no tokens are given, then data for all casks is returned.
       #
       # The pseudo-stanza "artifacts" is available.
       #

Library/Homebrew/cask/cmd/upgrade.rb

@@ -151,25 +151,25 @@ module Cask
         begin
           oh1 "Upgrading #{Formatter.identifier(old_cask)}"
 
-          # Start new Cask's installation steps
+          # Start new cask's installation steps
           new_cask_installer.check_conflicts
 
           puts new_cask_installer.caveats if new_cask_installer.caveats
 
           new_cask_installer.fetch
 
-          # Move the old Cask's artifacts back to staging
+          # Move the old cask's artifacts back to staging
           old_cask_installer.start_upgrade
           # And flag it so in case of error
           started_upgrade = true
 
-          # Install the new Cask
+          # Install the new cask
           new_cask_installer.stage
 
           new_cask_installer.install_artifacts
           new_artifacts_installed = true
 
-          # If successful, wipe the old Cask from staging
+          # If successful, wipe the old cask from staging
           old_cask_installer.finalize_upgrade
         rescue => e
           new_cask_installer.uninstall_artifacts if new_artifacts_installed

Library/Homebrew/cask/dsl.rb

@@ -212,7 +212,7 @@ module Cask
       end
     end
 
-    # depends_on uses a load method so that multiple stanzas can be merged
+    # `depends_on` uses a load method so that multiple stanzas can be merged.
     def depends_on(*args)
       @depends_on ||= DSL::DependsOn.new
       return @depends_on if args.empty?
@@ -286,7 +286,7 @@ module Cask
       end
     end
 
-    # No need to define it as its the default/superclass implementation.
+    # No need to define it as it's the default/superclass implementation.
     # rubocop:disable Style/MissingRespondToMissing
     def method_missing(method, *)
       if method

Library/Homebrew/cask/dsl/base.rb

@@ -22,7 +22,7 @@ module Cask
         @command.run!(executable, **options)
       end
 
-      # No need to define it as its the default/superclass implementation.
+      # No need to define it as it's the default/superclass implementation.
       # rubocop:disable Style/MissingRespondToMissing
       def method_missing(method, *)
         if method

Library/Homebrew/cask/dsl/caveats.rb

@@ -11,7 +11,7 @@ module Cask
     #
     # 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.
+    # convenience of cask authors.
     #
     # @api private
     class Caveats < Base

Library/Homebrew/cask/installer.rb

@@ -20,7 +20,7 @@ module Cask
   class Installer
     extend Predicable
     # TODO: it is unwise for Cask::Staged to be a module, when we are
-    #       dealing with both staged and unstaged Casks here. This should
+    #       dealing with both staged and unstaged casks here. This should
     #       either be a class which is only sometimes instantiated, or there
     #       should be explicit checks on whether staged state is valid in
     #       every method.

Library/Homebrew/cask/pkg.rb

@@ -139,7 +139,7 @@ module Cask
     end
 
     # Some packages leave broken symlinks around; we clean them out before
-    # attempting to `rmdir` to prevent extra cruft from lying around.
+    # attempting to `rmdir` to prevent extra cruft from accumulating.
     def clean_broken_symlinks(dir)
       dir.children.select(&method(:broken_symlink?)).each do |path|
         @command.run!("/bin/rm", args: ["--", path], sudo: true)

Library/Homebrew/cask_dependent.rb

 # typed: true
 # frozen_string_literal: true
 
-# An adapter for casks to provide dependency information in a formula-like interface
+# An adapter for casks to provide dependency information in a formula-like interface.
 class CaskDependent
   def initialize(cask)
     @cask = cask

Library/Homebrew/cleaner.rb

@@ -13,12 +13,12 @@
 class Cleaner
   include Context
 
-  # Create a cleaner for the given formula
+  # Create a cleaner for the given formula.
   def initialize(f)
     @f = f
   end
 
-  # Clean the keg of formula @f
+  # Clean the keg of the formula.
   def clean
     ObserverPathnameExtension.reset_counts!
 

Library/Homebrew/cleanup.rb

@@ -15,7 +15,7 @@ module Homebrew
     CLEANUP_DEFAULT_DAYS = 30
     private_constant :CLEANUP_DEFAULT_DAYS
 
-    # `Pathname` refinement with helper functions for cleaning up files.
+    # {Pathname} refinement with helper functions for cleaning up files.
     module CleanupRefinement
       refine Pathname do
         def incomplete?

Library/Homebrew/cli/named_args.rb

@@ -100,7 +100,7 @@ module Homebrew
         to_formulae_to_casks(method: :resolve, only: only)
       end
 
-      # Convert named arguments to `Tap`, `Formula` or `Cask` objects.
+      # Convert named arguments to {Tap}, {Formula} or {Cask} objects.
       # If both a formula and cask exist with the same name, returns the
       # formula and prints a warning unless `only` is specified.
       def to_objects(only: nil, method: nil)

Library/Homebrew/cmd/gist-logs.rb

@@ -91,7 +91,7 @@ module Homebrew
     s.freeze
   end
 
-  # Causes some terminals to display secure password entry indicators
+  # Causes some terminals to display secure password entry indicators.
   def noecho_gets
     system "stty -echo"
     result = $stdin.gets

Library/Homebrew/cmd/update-report.rb

@@ -311,7 +311,7 @@ class Reporter
         name
       end
 
-      # This means it is a Cask
+      # This means it is a cask
       if report[:DC].include? full_name
         next unless (HOMEBREW_PREFIX/"Caskroom"/new_name).exist?
 

Library/Homebrew/compat/cli/parser.rb

@@ -6,7 +6,7 @@ module Homebrew
     class Parser
       module Compat
         module DeprecatedArgs
-          # No need to define it as its the default/superclass implementation.
+          # No need to define it as it's the default/superclass implementation.
           # rubocop:disable Style/MissingRespondToMissing
           def method_missing(method, *)
             if ![:debug?, :quiet?, :verbose?, :value].include?(method) && !@printed_args_warning

Library/Homebrew/compilers.rb

@@ -27,10 +27,10 @@ class CompilerFailure
   end
 
   # Allows Apple compiler `fails_with` statements to keep using `build`
-  # even though `build` and `version` are the same internally
+  # even though `build` and `version` are the same internally.
   alias build version
 
-  # The cause is no longer used so we need not hold a reference to the string
+  # The cause is no longer used so we need not hold a reference to the string.
   def cause(_); end
 
   def self.for_standard(standard)

Library/Homebrew/cxxstdlib.rb

@@ -47,7 +47,7 @@ class CxxStdlib
   # If either package doesn't use C++, all is well.
   # libstdc++ and libc++ aren't ever intercompatible.
   # libstdc++ is compatible across Apple compilers, but
-  # not between Apple and GNU compilers, or between GNU compiler versions.
+  # not between Apple and GNU compilers, nor between GNU compiler versions.
   def compatible_with?(other)
     return true if type.nil? || other.type.nil?
 

Library/Homebrew/dependable.rb

@@ -7,8 +7,8 @@ require "options"
 #
 # @api private
 module Dependable
-  # `:run` and `:linked` are no longer used but keep them here to avoid them being
-  # misused in future.
+  # `:run` and `:linked` are no longer used but keep them here to avoid their
+  # misuse in future.
   RESERVED_TAGS = [:build, :optional, :recommended, :run, :test, :linked].freeze
 
   def build?