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

@@ -1,7 +1,7 @@
 # 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?

Library/Homebrew/dependency.rb

@@ -68,7 +68,7 @@ class Dependency
     "#<#{self.class.name}: #{name.inspect} #{tags.inspect}>"
   end
 
-  # Define marshaling semantics because we cannot serialize @env_proc
+  # Define marshaling semantics because we cannot serialize @env_proc.
   def _dump(*)
     Marshal.dump([name, tags])
   end
@@ -78,7 +78,7 @@ class Dependency
   end
 
   class << self
-    # Expand the dependencies of dependent recursively, optionally yielding
+    # Expand the dependencies of each dependent recursively, optionally yielding
     # `[dependent, dep]` pairs to allow callers to apply arbitrary filters to
     # the list.
     # The default filter, which is applied when a block is not given, omits
@@ -125,17 +125,17 @@ class Dependency
       end
     end
 
-    # Prune a dependency and its dependencies recursively
+    # Prune a dependency and its dependencies recursively.
     def prune
       throw(:action, :prune)
     end
 
-    # Prune a single dependency but do not prune its dependencies
+    # Prune a single dependency but do not prune its dependencies.
     def skip
       throw(:action, :skip)
     end
 
-    # Keep a dependency, but prune its dependencies
+    # Keep a dependency, but prune its dependencies.
     def keep_but_prune_recursive_deps
       throw(:action, :keep_but_prune_recursive_deps)
     end

Library/Homebrew/deprecate_disable.rb

@@ -1,7 +1,7 @@
 # typed: true
 # frozen_string_literal: true
 
-# Helper module for handling disable! and deprecate!
+# Helper module for handling `disable!` and `deprecate!`.
 #
 # @api private
 module DeprecateDisable

Library/Homebrew/description_cache_store.rb

@@ -6,7 +6,7 @@ require "cache_store"
 require "searchable"
 
 #
-# `DescriptionCacheStore` provides methods to fetch and mutate linkage-specific data used
+# {DescriptionCacheStore} provides methods to fetch and mutate linkage-specific data used
 # by the `brew linkage` command.
 #
 class DescriptionCacheStore < CacheStore
@@ -22,7 +22,7 @@ class DescriptionCacheStore < CacheStore
     database.set(formula_name, description)
   end
 
-  # Delete the formula description from the `DescriptionCacheStore`.
+  # Delete the formula description from the {DescriptionCacheStore}.
   #
   # @param formula_name [String] the name of the formula to delete
   # @return [nil]
@@ -31,6 +31,7 @@ class DescriptionCacheStore < CacheStore
   end
 
   # If the database is empty `update!` it with all known formulae.
+  #
   # @return [nil]
   def populate_if_empty!
     return unless database.empty?
@@ -38,7 +39,7 @@ class DescriptionCacheStore < CacheStore
     Formula.each { |f| update!(f.full_name, f.desc) }
   end
 
-  # Use an update report to update the `DescriptionCacheStore`.
+  # Use an update report to update the {DescriptionCacheStore}.
   #
   # @param report [Report] an update report generated by cmd/update.rb
   # @return [nil]
@@ -56,7 +57,7 @@ class DescriptionCacheStore < CacheStore
                                renamings.map(&:first))
   end
 
-  # Use an array of formula names to update the `DescriptionCacheStore`.
+  # Use an array of formula names to update the {DescriptionCacheStore}.
   #
   # @param formula_names [Array] the formulae to update
   # @return [nil]
@@ -70,7 +71,7 @@ class DescriptionCacheStore < CacheStore
     end
   end
 
-  # Use an array of formula names to delete them from the `DescriptionCacheStore`.
+  # Use an array of formula names to delete them from the {DescriptionCacheStore}.
   #
   # @param formula_names [Array] the formulae to delete
   # @return [nil]

Library/Homebrew/dev-cmd/audit.rb

@@ -760,7 +760,7 @@ module Homebrew
       "vbindiff"        => "3.0_beta",
     }.freeze
 
-    # used for formulae that are unstable but need CI run without being in homebrew/core
+    # Used for formulae that are unstable but need CI run without being in homebrew/core
     UNSTABLE_DEVEL_ALLOWLIST = {
     }.freeze
 

Library/Homebrew/dev-cmd/create.rb

@@ -63,7 +63,7 @@ module Homebrew
     end
   end
 
-  # Create a formula from a tarball URL
+  # Create a formula from a tarball URL.
   def create
     args = create_args.parse
 

Library/Homebrew/dev-cmd/pr-pull.rb

@@ -130,7 +130,7 @@ module Homebrew
   end
 
   # Cherry picks a single commit that modifies a single file.
-  # Potentially rewords this commit using `determine_bump_subject`.
+  # Potentially rewords this commit using {determine_bump_subject}.
   def reword_formula_commit(commit, file, reason: "", verbose: false, resolve: false, path: ".")
     formula_file = Pathname.new(path) / file
     formula_name = formula_file.basename.to_s.chomp(".rb")
@@ -154,7 +154,7 @@ module Homebrew
   end
 
   # Cherry picks multiple commits that each modify a single file.
-  # Words the commit according to `determine_bump_subject` with the body
+  # Words the commit according to {determine_bump_subject} with the body
   # corresponding to all the original commit messages combined.
   def squash_formula_commits(commits, file, reason: "", verbose: false, resolve: false, path: ".")
     odebug "Squashing #{file}: #{commits.join " "}"

Library/Homebrew/download_strategy.rb

@@ -255,7 +255,7 @@ class AbstractFileDownloadStrategy < AbstractDownloadStrategy
     @symlink_location = @cache/"#{name}--#{version}#{ext}"
   end
 
-  # Path for storing the completed download .
+  # Path for storing the completed download.
   #
   # @api public
   def cached_location

Library/Homebrew/exceptions.rb

@@ -210,7 +210,7 @@ class TapFormulaUnreadableError < TapFormulaUnavailableError
   end
 end
 
-# Raised when a formula with the same name is found multiple taps.
+# Raised when a formula with the same name is found in multiple taps.
 class TapFormulaAmbiguityError < RuntimeError
   attr_reader :name, :paths, :formulae
 

Library/Homebrew/extend/ENV/shared.rb

@@ -97,7 +97,7 @@ module SharedEnvExtension
   # This is done automatically for keg-only formulae.
   # <pre>ENV.prepend_path "PKG_CONFIG_PATH", "#{Formula["glib"].opt_lib}/pkgconfig"</pre>
   # Prepending a system path such as /usr/bin is a no-op so that requirements
-  # don't accidentally override superenv shims or formulae's `bin` directories, e.g.
+  # don't accidentally override superenv shims or formulae's `bin` directories.
   # <pre>ENV.prepend_path "PATH", which("emacs").dirname</pre>
   def prepend_path(key, path)
     return if %w[/usr/bin /bin /usr/sbin /sbin].include? path.to_s

Library/Homebrew/extend/ENV/super.rb

@@ -6,14 +6,14 @@ require "development_tools"
 
 # ### Why `superenv`?
 #
-# 1. Only specify the environment we need (NO LDFLAGS for cmake)
-# 2. Only apply compiler specific options when we are calling that compiler
-# 3. Force all incpaths and libpaths into the cc instantiation (less bugs)
+# 1. Only specify the environment we need (*NO* LDFLAGS for cmake)
+# 2. Only apply compiler-specific options when we are calling that compiler
+# 3. Force all incpaths and libpaths into the cc instantiation (fewer bugs)
 # 4. Cater toolchain usage to specific Xcode versions
 # 5. Remove flags that we don't want or that will break builds
 # 6. Simpler code
-# 7. Simpler formula that *just work*
-# 8. Build-system agnostic configuration of the tool-chain
+# 7. Simpler formulae that *just work*
+# 8. Build-system agnostic configuration of the toolchain
 module Superenv
   include SharedEnvExtension
 

Library/Homebrew/extend/os/linux/hardware/cpu.rb

@@ -75,7 +75,7 @@ module Hardware
       end
 
       # Compatibility with Mac method, which returns lowercase symbols
-      # instead of strings
+      # instead of strings.
       def features
         @features ||= flags[1..].map(&:intern)
       end

Library/Homebrew/extend/os/linux/linkage_checker.rb

@@ -17,7 +17,6 @@ class LinkageChecker
     librt.so.1
     libthread_db.so.1
     libutil.so.1
-
     libgcc_s.so.1
     libgomp.so.1
     libstdc++.so.6

Library/Homebrew/extend/os/mac/extend/ENV/std.rb

@@ -101,8 +101,8 @@ module Stdenv
     append_path "CMAKE_FRAMEWORK_PATH", "#{sdk}/System/Library/Frameworks"
   end
 
-  # Some configure scripts won't find libxml2 without help
-  # This is a no-op with macOS SDK 10.15.4 and later
+  # Some configure scripts won't find libxml2 without help.
+  # This is a no-op with macOS SDK 10.15.4 and later.
   def libxml2
     sdk = self["SDKROOT"] || MacOS.sdk_path_if_needed
     if !sdk

Library/Homebrew/extend/os/mac/hardware/cpu.rb

@@ -54,8 +54,8 @@ module Hardware
         end
       end
 
-      # Returns an array that's been extended with ArchitectureListExtension,
-      # which provides helpers like #as_arch_flags and #as_cmake_arch_flags.
+      # Returns an array that's been extended with {ArchitectureListExtension},
+      # which provides helpers like `#as_arch_flags`.
       def universal_archs
         # Amazingly, this order (64, then 32) matters. It shouldn't, but it
         # does. GCC (some versions? some systems?) can blow up if the other
@@ -66,7 +66,7 @@ module Hardware
 
       # True when running under an Intel-based shell via Rosetta on an
       # Apple Silicon Mac. This can be detected via seeing if there's a
-      # conflict between what `uname` report and the underlying `sysctl` flags,
+      # conflict between what `uname` reports and the underlying `sysctl` flags,
       # since the `sysctl` flags don't change behaviour under Rosetta.
       def in_rosetta?
         intel? && physical_cpu_arm64?

Library/Homebrew/extend/os/mac/keg_relocate.rb

@@ -39,10 +39,10 @@ class Keg
     end
   end
 
-  # Detects the C++ dynamic libraries in place, scanning the dynamic links
+  # Detects the C++ dynamic libraries in-place, scanning the dynamic links
   # of the files within the keg.
   # Note that this doesn't attempt to distinguish between libstdc++ versions,
-  # for instance between Apple libstdc++ and GNU libstdc++
+  # for instance between Apple libstdc++ and GNU libstdc++.
   def detect_cxx_stdlibs(options = {})
     skip_executables = options.fetch(:skip_executables, false)
     results = Set.new

Library/Homebrew/extend/pathname.rb

@@ -150,7 +150,7 @@ class Pathname
   # @private
   alias old_write write
 
-  # We assume this pathname object is a file, obviously
+  # We assume this pathname object is a file, obviously.
   def write(content, *open_args)
     raise "Will not overwrite #{self}" if exist?
 
@@ -214,7 +214,7 @@ class Pathname
   # @private
   alias extname_old extname
 
-  # Extended to support common double extensions
+  # Extended to support common double extensions.
   def extname(path = to_s)
     basename = File.basename(path)
 
@@ -230,7 +230,7 @@ class Pathname
     File.extname(basename)
   end
 
-  # For filetypes we support, basename without extension
+  # For filetypes we support, returns basename without extension.
   def stem
     File.basename((path = to_s), extname(path))
   end
@@ -329,7 +329,7 @@ class Pathname
     quiet_system "/usr/bin/install-info", "--delete", "--quiet", to_s, "#{dirname}/dir"
   end
 
-  # Writes an exec script in this folder for each target pathname
+  # Writes an exec script in this folder for each target pathname.
   def write_exec_script(*targets)
     targets.flatten!
     if targets.empty?
@@ -346,7 +346,7 @@ class Pathname
     end
   end
 
-  # Writes an exec script that sets environment variables
+  # Writes an exec script that sets environment variables.
   def write_env_script(target, args, env = nil)
     unless env
       env = args
@@ -361,7 +361,7 @@ class Pathname
     SH
   end
 
-  # Writes a wrapper env script and moves all files to the dst
+  # Writes a wrapper env script and moves all files to the dst.
   def env_script_all_files(dst, env)
     dst.mkpath
     Pathname.glob("#{self}/*") do |file|
@@ -373,7 +373,7 @@ class Pathname
     end
   end
 
-  # Writes an exec script that invokes a Java jar
+  # Writes an exec script that invokes a Java jar.
   def write_jar_script(target_jar, script_name, java_opts = "", java_version: nil)
     (self/script_name).write <<~EOS
       #!/bin/bash

Library/Homebrew/formula.rb

@@ -67,7 +67,7 @@ class Formula
   # Sometimes we have to change a bit before we install. Mostly we
   # prefer a patch but if you need the `prefix` of this formula in the
   # patch you have to resort to `inreplace`, because in the patch
-  # you don't have access to any var defined by the formula. Only
+  # you don't have access to any variable defined by the formula. Only
   # `HOMEBREW_PREFIX` is available in the embedded patch.
   #
   # `inreplace` supports regular expressions:
@@ -101,7 +101,7 @@ class Formula
   attr_reader :path
 
   # The {Tap} instance associated with this {Formula}.
-  # If it's <code>nil</code>, then this formula is loaded from path or URL.
+  # If it's `nil`, then this formula is loaded from a path or URL.
   # @private
   attr_reader :tap
 
@@ -109,7 +109,7 @@ class Formula
   # @private
   attr_reader :force_bottle
 
-  # The stable (and default) {SoftwareSpec} for this {Formula}
+  # The stable (and default) {SoftwareSpec} for this {Formula}.
   # This contains all the attributes (e.g. URL, checksum) that apply to the
   # stable version of this formula.
   # @private
@@ -121,7 +121,7 @@ class Formula
   end
 
   # The HEAD {SoftwareSpec} for this {Formula}.
-  # Installed when using `brew install --HEAD`
+  # Installed when using `brew install --HEAD`.
   # This is always installed with the version `HEAD` and taken from the latest
   # commit in the version control system.
   # `nil` if there is no HEAD version.
@@ -150,7 +150,7 @@ class Formula
   # @see .revision=
   attr_reader :revision
 
-  # Used to change version schemes for packages
+  # Used to change version schemes for packages.
   # @see .version_scheme=
   attr_reader :version_scheme
 
@@ -179,7 +179,7 @@ class Formula
   # @return [BuildOptions]
   attr_accessor :build
 
-  # A Boolean indicating whether this formula should be considered outdated
+  # Whether this formula should be considered outdated
   # if the target of the alias it was installed with has since changed.
   # Defaults to true.
   # @return [Boolean]
@@ -426,14 +426,14 @@ class Formula
     end.compact.sort_by(&:version).reverse
   end
 
-  # A named Resource for the currently active {SoftwareSpec}.
+  # A named {Resource} for the currently active {SoftwareSpec}.
   # Additional downloads can be defined as {#resource}s.
   # {Resource#stage} will create a temporary directory and yield to a block.
   # <pre>resource("additional_files").stage { bin.install "my/extra/tool" }</pre>
   # @!method resource
   delegate resource: :active_spec
 
-  # An old name for the formula
+  # An old name for the formula.
   def oldname
     @oldname ||= if tap
       formula_renames = tap.formula_renames
@@ -441,7 +441,7 @@ class Formula
     end
   end
 
-  # All aliases for the formula
+  # All aliases for the formula.
   def aliases
     @aliases ||= if tap
       tap.alias_reverse_table[full_name].to_a.map do |a|
@@ -597,7 +597,7 @@ class Formula
   end
 
   # The parent of the prefix; the named directory in the cellar containing all
-  # installed versions of this software
+  # installed versions of this software.
   # @private
   def rack
     Pathname.new("#{HOMEBREW_CELLAR}/#{name}")
@@ -678,7 +678,7 @@ class Formula
   # This is symlinked into `HOMEBREW_PREFIX` after installation or with
   # `brew link` for formulae that are not keg-only.
   # Often one of the more specific `man` functions should be used instead,
-  # e.g. {#man1}
+  # e.g. {#man1}.
   def man
     share/"man"
   end
@@ -763,10 +763,10 @@ class Formula
   # Installing something into another custom directory?
   # <pre>(share/"concept2").install "ducks.txt"</pre>
   #
-  # Install `./example_code/simple/ones` to share/demos
+  # Install `./example_code/simple/ones` to `share/demos`:
   # <pre>(share/"demos").install "example_code/simple/ones"</pre>
   #
-  # Install `./example_code/simple/ones` to share/demos/examples
+  # Install `./example_code/simple/ones` to `share/demos/examples`:
   # <pre>(share/"demos").install "example_code/simple/ones" => "examples"</pre>
   def share
     prefix/"share"
@@ -786,7 +786,7 @@ class Formula
   # The directory where Emacs Lisp files should be installed, with the
   # formula name appended to avoid linking conflicts.
   #
-  # Install an Emacs mode included with a software package:
+  # To install an Emacs mode included with a software package:
   # <pre>elisp.install "contrib/emacs/example-mode.el"</pre>
   def elisp
     prefix/"share/emacs/site-lisp"/name
@@ -886,7 +886,7 @@ class Formula
     HOMEBREW_LOGS + name
   end
 
-  # The prefix, if any, to use in filenames for logging current activity
+  # The prefix, if any, to use in filenames for logging current activity.
   def active_log_prefix
     if active_log_type
       "#{active_log_type}."
@@ -895,7 +895,7 @@ class Formula
     end
   end
 
-  # Runs a block with the given log type in effect for its duration
+  # Runs a block with the given log type in effect for its duration.
   def with_logging(log_type)
     old_log_type = @active_log_type
     @active_log_type = log_type
@@ -1002,7 +1002,7 @@ class Formula
   # Can be overridden to selectively disable bottles from formulae.
   # Defaults to true so overridden version does not have to check if bottles
   # are supported.
-  # Replaced by {.pour_bottle}'s `satisfy` method if it is specified.
+  # Replaced by {.pour_bottle?}'s `satisfy` method if it is specified.
   def pour_bottle?
     true
   end
@@ -1047,7 +1047,7 @@ class Formula
     @prefix_returns_versioned_prefix = false
   end
 
-  # Warn the user about any Homebrew-specific issues or quirks for this package
+  # Warn the user about any Homebrew-specific issues or quirks for this package.
   # These should not contain setup instructions that would apply to installation
   # through a different package manager on a different OS.
   # @return [String]
@@ -1176,8 +1176,8 @@ class Formula
     patchlist.each(&:apply)
   end
 
-  # yields |self,staging| with current working directory set to the uncompressed tarball
-  # where staging is a Mktemp staging context
+  # Yields |self,staging| with current working directory set to the uncompressed tarball
+  # where staging is a {Mktemp} staging context.
   # @private
   def brew(fetch: true, keep_tmp: false, interactive: false)
     @prefix_returns_versioned_prefix = true
@@ -1393,7 +1393,7 @@ class Formula
   # Setting `CMAKE_FIND_FRAMEWORK` to "LAST" tells CMake to search for our
   # libraries before trying to utilize Frameworks, many of which will be from
   # 3rd party installs.
-  # Note: there isn't a std_autotools variant because autotools is a lot
+  # Note that there isn't a std_autotools variant because autotools is a lot
   # less consistent and the standard parameters are more memorable.
   def std_cmake_args
     args = %W[
@@ -1611,7 +1611,7 @@ class Formula
   end
 
   # Returns a Keg for the opt_prefix or installed_prefix if they exist.
-  # If not, return nil.
+  # If not, return `nil`.
   # @private
   def any_installed_keg
     Formula.cache[:any_installed_keg] ||= {}
@@ -1654,7 +1654,7 @@ class Formula
     deps
   end
 
-  # Returns a list of Formula objects that are required at runtime.
+  # Returns a list of {Formula} objects that are required at runtime.
   # @private
   def runtime_formula_dependencies(read_from_tab: true, undeclared: true)
     cache_key = "#{full_name}-#{read_from_tab}-#{undeclared}"
@@ -1688,7 +1688,7 @@ class Formula
   end
 
   # Returns a list of formulae depended on by this formula that aren't
-  # installed
+  # installed.
   def missing_dependencies(hide: nil)
     hide ||= []
     runtime_formula_dependencies.select do |f|
@@ -1872,10 +1872,10 @@ class Formula
     HOMEBREW_LIBRARY_PATH/"test/support/fixtures"/file
   end
 
-  # This method is overridden in {Formula} subclasses to provide the installation instructions.
-  # The sources (from {.url}) are downloaded, hash-checked and
-  # Homebrew changes into a temporary directory where the
-  # archive was unpacked or repository cloned.
+  # This method is overridden in {Formula} subclasses to provide the
+  # installation instructions. The sources (from {.url}) are downloaded,
+  # hash-checked and then Homebrew changes into a temporary directory where the
+  # archive is unpacked or repository cloned.
   # <pre>def install
   #   system "./configure", "--prefix=#{prefix}"
   #   system "make", "install"
@@ -1932,14 +1932,14 @@ class Formula
   # For CMake we have some necessary defaults in {#std_cmake_args}:
   # <pre>system "cmake", ".", *std_cmake_args</pre>
   #
-  # If the arguments given to configure (or make or cmake) are depending
+  # If the arguments given to `configure` (or `make` or `cmake`) are depending
   # on options defined above, we usually make a list first and then
-  # use the `args << if <condition>` to append to:
+  # use the `args << if <condition>` to append each:
   # <pre>args = ["--with-option1", "--with-option2"]
   # args << "--without-gcc" if ENV.compiler == :clang
   #
   # # Most software still uses `configure` and `make`.
-  # # Check with `./configure --help` what our options are.
+  # # Check with `./configure --help` for what our options are.
   # system "./configure", "--disable-debug", "--disable-dependency-tracking",
   #                       "--disable-silent-rules", "--prefix=#{prefix}",
   #                       *args # our custom arg list (needs `*` to unpack)
@@ -2099,7 +2099,7 @@ class Formula
     FileUtils.chdir(name, &block)
   end
 
-  # Run `xcodebuild` without Homebrew's compiler environment variables set.
+  # Runs `xcodebuild` without Homebrew's compiler environment variables set.
   def xcodebuild(*args)
     removed = ENV.remove_cc_etc
     system "xcodebuild", *args
@@ -2150,7 +2150,7 @@ class Formula
     exit! 1 # never gets here unless exec threw or failed
   end
 
-  # Common environment variables used at both build and test time
+  # Common environment variables used at both build and test time.
   def common_stage_test_env
     {
       _JAVA_OPTIONS: "-Duser.home=#{HOMEBREW_CACHE}/java_cache",
@@ -2289,7 +2289,7 @@ class Formula
 
     # @!attribute [w] revision
     # Used for creating new Homebrew versions of software without new upstream
-    # versions. For example, if we bump the major version of a library this
+    # versions. For example, if we bump the major version of a library that this
     # {Formula} {.depends_on} then we may need to update the `revision` of this
     # {Formula} to install a new version linked against the new library version.
     # `0` if unset.
@@ -2300,7 +2300,7 @@ class Formula
     # @!attribute [w] version_scheme
     # Used for creating new Homebrew version schemes. For example, if we want
     # to change version scheme from one to another, then we may need to update
-    # `version_scheme` of this {Formula} to be able to use new version scheme.
+    # `version_scheme` of this {Formula} to be able to use new version scheme,
     # e.g. to move from 20151020 scheme to 1.0.0 we need to increment
     # `version_scheme`. Without this, the prior scheme will always equate to a
     # higher version.
@@ -2360,7 +2360,7 @@ class Formula
     # @!attribute [w] sha256
     # @scope class
     # To verify the cached download's integrity and security we verify the
-    # SHA-256 hash matches which we've declared in the {Formula}. To quickly fill
+    # SHA-256 hash matches what we've declared in the {Formula}. To quickly fill
     # this value you can leave it blank and run `brew fetch --force` and it'll
     # tell you the currently valid value.
     #
@@ -2381,10 +2381,10 @@ class Formula
     # It'll be handled for you by the Brew Test Bot.
     #
     # <pre>bottle do
-    #   root_url "https://example.com" # Optional root to calculate bottle URLs
+    #   root_url "https://example.com" # Optional root to calculate bottle URLs.
     #   prefix "/opt/homebrew" # Optional HOMEBREW_PREFIX in which the bottles were built.
     #   cellar "/opt/homebrew/Cellar" # Optional HOMEBREW_CELLAR in which the bottles were built.
-    #   rebuild 1 # Making the old bottle outdated without bumping the version/revision of the formula.
+    #   rebuild 1 # Marks the old bottle as outdated without bumping the version/revision of the formula.
     #   sha256 "ef65c759c5097a36323fa9c77756468649e8d1980a3a4e05695c05e39568967c" => :catalina
     #   sha256 "28f4090610946a4eb207df102d841de23ced0d06ba31cb79e040d883906dcd4f" => :mojave
     #   sha256 "91dd0caca9bd3f38c439d5a7b6f68440c4274945615fae035ff0a369264b8a2f" => :high_sierra
@@ -2423,7 +2423,7 @@ class Formula
     # @!attribute [w] stable
     # Allows adding {.depends_on} and {Patch}es just to the {.stable} {SoftwareSpec}.
     # This is required instead of using a conditional.
-    # It is preferrable to also pull the {url} and {.sha256} into the block if one is added.
+    # It is preferrable to also pull the {url} and {sha256= sha256} into the block if one is added.
     #
     # <pre>stable do
     #   url "https://example.com/foo-1.0.tar.gz"
@@ -2467,7 +2467,7 @@ class Formula
       end
     end
 
-    # Additional downloads can be defined as resources and accessed in the
+    # Additional downloads can be defined as {resource}s and accessed in the
     # install method. Resources can also be defined inside a {.stable} or
     # {.head} block. This mechanism replaces ad-hoc "subformula" classes.
     # <pre>resource "additional_files" do
@@ -2487,20 +2487,20 @@ class Formula
     # The dependencies for this formula. Use strings for the names of other
     # formulae. Homebrew provides some :special dependencies for stuff that
     # requires certain extra handling (often changing some ENV vars or
-    # deciding if to use the system provided version or not.)
+    # deciding if to use the system provided version or not).
     # <pre># `:build` means this dep is only needed during build.
     # depends_on "cmake" => :build</pre>
     # <pre># `:recommended` dependencies are built by default.
     # # But a `--without-...` option is generated to opt-out.
     # depends_on "readline" => :recommended</pre>
-    # <pre># `:optional` dependencies are NOT built by default.
-    # # But a `--with-...` options is generated.
+    # <pre># `:optional` dependencies are NOT built by default unless the
+    # # auto-generated `--with-...` option is passed.
     # depends_on "glib" => :optional</pre>
     # <pre># If you need to specify that another formula has to be built with/out
     # # certain options (note, no `--` needed before the option):
     # depends_on "zeromq" => "with-pgm"
     # depends_on "qt" => ["with-qtdbus", "developer"] # Multiple options.</pre>
-    # <pre># Optional and enforce that boost is built with `--with-c++11`.
+    # <pre># Optional and enforce that "boost" is built with `--with-c++11`.
     # depends_on "boost" => [:optional, "with-c++11"]</pre>
     # <pre># If a dependency is only needed in certain cases:
     # depends_on "sqlite" if MacOS.version >= :catalina
@@ -2519,8 +2519,8 @@ class Formula
     end
 
     # Indicates use of dependencies provided by macOS.
-    # On macOS this is a no-op (as we use the system libraries there).
-    # On Linux this will act as `depends_on`.
+    # On macOS this is a no-op (as we use the provided system libraries).
+    # On Linux this will act as {.depends_on}.
     def uses_from_macos(dep, bounds = {})
       specs.each { |spec| spec.uses_from_macos(dep, bounds) }
     end
@@ -2544,7 +2544,7 @@ class Formula
     # @!attribute [w] option
     # Options can be used as arguments to `brew install`.
     # To switch features on/off: `"with-something"` or `"with-otherthing"`.
-    # To use other software: `"with-other-software"` or `"without-foo"`
+    # To use other software: `"with-other-software"` or `"without-foo"`.
     # Note that for {.depends_on} that are `:optional` or `:recommended`, options
     # are generated automatically.
     #
@@ -2553,7 +2553,7 @@ class Formula
     # - `:universal`: build a universal binary/library (e.g. on newer Intel Macs
     #   this means a combined x86_64/x86 binary/library).
     # <pre>option "with-spam", "The description goes here without a dot at the end"</pre>
-    # <pre>option "with-qt", "Text here overwrites the autogenerated one from 'depends_on "qt" => :optional'"</pre>
+    # <pre>option "with-qt", "Text here overwrites what's autogenerated by 'depends_on "qt" => :optional'"</pre>
     # <pre>option :universal</pre>
     def option(name, description = "")
       specs.each { |spec| spec.option(name, description) }
@@ -2653,7 +2653,7 @@ class Formula
       @keg_only_reason = KegOnlyReason.new(reason, explanation)
     end
 
-    # Pass `:skip` to this method to disable post-install stdlib checking
+    # Pass `:skip` to this method to disable post-install stdlib checking.
     def cxxstdlib_check(check_type)
       define_method(:skip_cxxstdlib_check?) { true } if check_type == :skip
     end
@@ -2694,8 +2694,8 @@ class Formula
     #
     # We want tests that don't require any user input
     # and test the basic functionality of the application.
-    # For example foo build-foo input.foo is a good test
-    # and foo --version and foo --help are bad tests.
+    # For example, `foo build-foo input.foo` is a good test
+    # and `foo --version` or `foo --help` are bad tests.
     # However, a bad test is better than no test at all.
     #
     # @see https://docs.brew.sh/Formula-Cookbook#add-a-test-to-the-formula Tests
@@ -2723,7 +2723,7 @@ class Formula
     # Livecheck can be used to check for newer versions of the software.
     # This method evaluates the DSL specified in the livecheck block of the
     # {Formula} (if it exists) and sets the instance variables of a Livecheck
-    # object accordingly. This is used by brew livecheck to check for newer
+    # object accordingly. This is used by `brew livecheck` to check for newer
     # versions of the software.
     #
     # <pre>livecheck do
@@ -2807,7 +2807,7 @@ class Formula
       @disabled == true
     end
 
-    # The reason for a {Formula} is disabled.
+    # The reason this {Formula} is disabled.
     # Returns `nil` if no reason was provided or the formula is not disabled.
     # @return [String, Symbol]
     attr_reader :disable_reason

Library/Homebrew/formula_assertions.rb

@@ -11,7 +11,7 @@ module Homebrew
     require "test/unit/assertions"
     include ::Test::Unit::Assertions
 
-    # Returns the output of running cmd, and asserts the exit status
+    # Returns the output of running cmd, and asserts the exit status.
     # @api public
     def shell_output(cmd, result = 0)
       ohai cmd

Library/Homebrew/formula_info.rb

@@ -5,7 +5,7 @@
 #
 # @api private
 class FormulaInfo
-  # The whole info structure parsed from the JSON
+  # The whole info structure parsed from the JSON.
   attr_accessor :info
 
   def initialize(info)

Library/Homebrew/formula_support.rb

@@ -4,7 +4,7 @@
 # Used to track formulae that cannot be installed at the same time.
 FormulaConflict = Struct.new(:name, :reason)
 
-# Used to annotate formulae that duplicate macOS provided software
+# Used to annotate formulae that duplicate macOS-provided software
 # or cause conflicts when linked in.
 class KegOnlyReason
   attr_reader :reason

Library/Homebrew/formulary.rb

@@ -5,7 +5,7 @@ require "digest/md5"
 require "extend/cachable"
 require "tab"
 
-# The Formulary is responsible for creating instances of {Formula}.
+# The {Formulary} is responsible for creating instances of {Formula}.
 # It is not meant to be used directly from formulae.
 #
 # @api private
@@ -111,7 +111,7 @@ module Formulary
     class_name
   end
 
-  # A FormulaLoader returns instances of formulae.
+  # A {FormulaLoader} returns instances of formulae.
   # Subclasses implement loaders for particular sources of formulae.
   class FormulaLoader
     include Context
@@ -129,7 +129,6 @@ module Formulary
     end
 
     # Gets the formula instance.
-    #
     # `alias_path` can be overridden here in case an alias was used to refer to
     # a formula that was loaded in another way.
     def get_formula(spec, alias_path: nil, force_bottle: false, flags: [])
@@ -300,7 +299,7 @@ module Formulary
     end
   end
 
-  # Pseudo-loader which will raise a `FormulaUnavailableError` when trying to load the corresponding formula.
+  # 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)
@@ -313,7 +312,7 @@ module Formulary
 
   # Load formulae directly from their contents.
   class FormulaContentsLoader < FormulaLoader
-    # The formula's contents
+    # The formula's contents.
     attr_reader :contents
 
     def initialize(name, path, contents)
@@ -328,7 +327,7 @@ module Formulary
     end
   end
 
-  # Return a Formula instance for the given reference.
+  # Return a {Formula} instance for the given reference.
   # `ref` is a string containing:
   #
   # * a formula name
@@ -353,8 +352,7 @@ module Formulary
     formula
   end
 
-  # Return a Formula instance for the given rack.
-  # It will auto resolve formula's spec when requested spec is nil
+  # Return a {Formula} instance for the given rack.
   #
   # @param spec when nil, will auto resolve the formula's spec.
   # @param :alias_path will be used if the formula is found not to be
@@ -372,7 +370,7 @@ module Formulary
     end
   end
 
-  # Return whether given rack is keg-only
+  # Return whether given rack is keg-only.
   def self.keg_only?(rack)
     Formulary.from_rack(rack).keg_only?
   rescue FormulaUnavailableError, TapFormulaAmbiguityError, TapFormulaWithOldnameAmbiguityError
@@ -406,7 +404,7 @@ module Formulary
     f
   end
 
-  # Return a Formula instance directly from contents
+  # Return a {Formula} instance directly from contents.
   def self.from_contents(name, path, contents, spec = :stable, alias_path: nil, force_bottle: false, flags: [])
     FormulaContentsLoader.new(name, path, contents)
                          .get_formula(spec, alias_path: alias_path, force_bottle: force_bottle, flags: flags)

Library/Homebrew/keg.rb

@@ -75,7 +75,7 @@ class Keg
     end
   end
 
-  # locale-specific directories have the form language[_territory][.codeset][@modifier]
+  # Locale-specific directories have the form `language[_territory][.codeset][@modifier]`
   LOCALEDIR_RX = %r{(locale|man)/([a-z]{2}|C|POSIX)(_[A-Z]{2})?(\.[a-zA-Z\-0-9]+(@.+)?)?}.freeze
   INFOFILE_RX = %r{info/([^.].*?\.info|dir)$}.freeze
   KEG_LINK_DIRECTORIES = %w[

Library/Homebrew/keg_relocate.rb

@@ -8,7 +8,7 @@ class Keg
 
   Relocation = Struct.new(:old_prefix, :old_cellar, :old_repository,
                           :new_prefix, :new_cellar, :new_repository) do
-    # Use keyword args instead of positional args for initialization
+    # Use keyword args instead of positional args for initialization.
     def initialize(**kwargs)
       super(*members.map { |k| kwargs[k] })
     end

Library/Homebrew/language/go.rb

@@ -9,9 +9,9 @@ module Language
   # @api public
   module Go
     # Given a set of resources, stages them to a gopath for
-    # building go software.
+    # building Go software.
     # The resource names should be the import name of the package,
-    # e.g. `resource "github.com/foo/bar"`
+    # e.g. `resource "github.com/foo/bar"`.
     def self.stage_deps(resources, target)
       if resources.empty?
         if Homebrew::EnvConfig.developer?

Library/Homebrew/language/python.rb

@@ -146,6 +146,7 @@ module Language
       # Instantiates, creates, and yields a {Virtualenv} object for use from
       # {Formula#install}, which provides helper methods for instantiating and
       # installing packages into a Python virtualenv.
+      #
       # @param venv_root [Pathname, String] the path to the root of the virtualenv
       #   (often `libexec/"venv"`)
       # @param python [String] which interpreter to use (e.g. "python3"
@@ -179,10 +180,11 @@ module Language
 
       # Returns true if a formula option for the specified python is currently
       # active or if the specified python is required by the formula. Valid
-      # inputs are "python", "python2", :python, and :python2. Note that
+      # inputs are "python", "python2", and :python3. Note that
       # "with-python", "without-python", "with-python@2", and "without-python@2"
       # formula options are handled correctly even if not associated with any
       # corresponding depends_on statement.
+      #
       # @api private
       def needs_python?(python)
         return true if build.with?(python)
@@ -193,7 +195,7 @@ module Language
       # Helper method for the common case of installing a Python application.
       # Creates a virtualenv in `libexec`, installs all `resource`s defined
       # on the formula, and then installs the formula. An options hash may be
-      # passed (e.g., `:using => "python"`) to override the default, guessed
+      # passed (e.g. `:using => "python"`) to override the default, guessed
       # formula preference for python or python@x.y, or to resolve an ambiguous
       # case where it's not clear whether python or python@x.y should be the
       # default guess.
@@ -222,10 +224,11 @@ module Language
       class Virtualenv
         # Initializes a Virtualenv instance. This does not create the virtualenv
         # on disk; {#create} does that.
-        # @param formula [Formula] the active Formula
+        #
+        # @param formula [Formula] the active {Formula}
         # @param venv_root [Pathname, String] the path to the root of the
         #   virtualenv
-        # @param python [String] which interpreter to use, i.e. "python" or
+        # @param python [String] which interpreter to use, e.g. "python" or
         #   "python2"
         def initialize(formula, venv_root, python)
           @formula = formula
@@ -233,8 +236,8 @@ module Language
           @python = python
         end
 
-        # Obtains a copy of the virtualenv library and creates a new virtualenv
-        # on disk.
+        # Obtains a copy of the virtualenv library and creates a new virtualenv on disk.
+        #
         # @return [void]
         def create
           return if (@venv_root/"bin/python").exist?
@@ -284,8 +287,9 @@ module Language
         end
 
         # Installs packages represented by `targets` into the virtualenv.
+        #
         # @param targets [String, Pathname, Resource,
-        #   Array<String, Pathname, Resource>] (A) token(s) passed to pip
+        #   Array<String, Pathname, Resource>] (A) token(s) passed to `pip`
         #   representing the object to be installed. This can be a directory
         #   containing a setup.py, a {Resource} which will be staged and
         #   installed, or a package identifier to be fetched from PyPI.
@@ -307,7 +311,8 @@ module Language
         end
 
         # Installs packages represented by `targets` into the virtualenv, but
-        #   unlike {#pip_install} also links new scripts to {Formula#bin}.
+        # unlike {#pip_install} also links new scripts to {Formula#bin}.
+        #
         # @param (see #pip_install)
         # @return (see #pip_install)
         def pip_install_and_link(targets)

Library/Homebrew/linkage_cache_store.rb

@@ -5,7 +5,7 @@ require "set"
 require "cache_store"
 
 #
-# `LinkageCacheStore` provides methods to fetch and mutate linkage-specific data used
+# {LinkageCacheStore} provides methods to fetch and mutate linkage-specific data used
 # by the `brew linkage` command.
 #
 class LinkageCacheStore < CacheStore
@@ -17,7 +17,7 @@ class LinkageCacheStore < CacheStore
     super(database)
   end
 
-  # Returns `true` if the database has any value for the current `keg_path`
+  # Returns `true` if the database has any value for the current `keg_path`.
   #
   # @return [Boolean]
   def keg_exists?
@@ -25,7 +25,7 @@ class LinkageCacheStore < CacheStore
   end
 
   # Inserts dylib-related information into the cache if it does not exist or
-  # updates data into the linkage cache if it does exist
+  # updates data into the linkage cache if it does exist.
   #
   # @param hash_values [Hash] hash containing KVPs of { :type => Hash }
   # @return [nil]
@@ -41,7 +41,7 @@ class LinkageCacheStore < CacheStore
     database.set @keg_path, hash_values
   end
 
-  # @param type [Symbol] the type to fetch from the `LinkageCacheStore`
+  # @param type [Symbol] the type to fetch from the {LinkageCacheStore}
   # @raise  [TypeError] error if the type is not in `HASH_LINKAGE_TYPES`
   # @return [Hash]
   def fetch(type)
@@ -56,7 +56,7 @@ class LinkageCacheStore < CacheStore
     fetch_hash_values(type)
   end
 
-  # Delete the keg from the `LinkageCacheStore`
+  # Delete the keg from the {LinkageCacheStore}
   #
   # @return [nil]
   def delete!

Library/Homebrew/linkage_checker.rb

@@ -299,7 +299,7 @@ class LinkageChecker
   end
 
   # Display a list of things.
-  # Things may either be an array, or a hash of (label -> array)
+  # Things may either be an array, or a hash of (label -> array).
   def display_items(label, things, puts_output: true)
     return if things.empty?
 

Library/Homebrew/livecheck.rb

@@ -1,14 +1,14 @@
 # typed: true
 # frozen_string_literal: true
 
-# The `Livecheck` class implements the DSL methods used in a formula's
+# The {Livecheck} class implements the DSL methods used in a formula's
 # `livecheck` block and stores related instance variables. Most of these methods
 # also return the related instance variable when no argument is provided.
 #
 # This information is used by the `brew livecheck` command to control its
 # behavior.
 class Livecheck
-  # A very brief description of why the formula is skipped (e.g., `No longer
+  # A very brief description of why the formula is skipped (e.g. `No longer
   # developed or maintained`).
   # @return [String, nil]
   attr_reader :skip_msg
@@ -24,6 +24,7 @@ class Livecheck
 
   # Sets the `@regex` instance variable to the provided `Regexp` or returns the
   # `@regex` instance variable when no argument is provided.
+  #
   # @param pattern [Regexp] regex to use for matching versions in content
   # @return [Regexp, nil]
   def regex(pattern = nil)
@@ -40,7 +41,8 @@ class Livecheck
   # Sets the `@skip` instance variable to `true` and sets the `@skip_msg`
   # instance variable if a `String` is provided. `@skip` is used to indicate
   # that the formula should be skipped and the `skip_msg` very briefly describes
-  # why the formula is skipped (e.g., `No longer developed or maintained`).
+  # why the formula is skipped (e.g. "No longer developed or maintained").
+  #
   # @param skip_msg [String] string describing why the formula is skipped
   # @return [Boolean]
   def skip(skip_msg = nil)
@@ -60,8 +62,9 @@ class Livecheck
 
   # Sets the `@strategy` instance variable to the provided `Symbol` or returns
   # the `@strategy` instance variable when no argument is provided. The strategy
-  # symbols use snake case (e.g., `:page_match`) and correspond to the strategy
+  # symbols use snake case (e.g. `:page_match`) and correspond to the strategy
   # file name.
+  #
   # @param symbol [Symbol] symbol for the desired strategy
   # @return [Symbol, nil]
   def strategy(symbol = nil)
@@ -78,7 +81,8 @@ class Livecheck
   # Sets the `@url` instance variable to the provided argument or returns the
   # `@url` instance variable when no argument is provided. The argument can be
   # a `String` (a URL) or a supported `Symbol` corresponding to a URL in the
-  # formula (e.g., `:stable`, `:homepage`, or `:head`).
+  # formula (e.g. `:stable`, `:homepage`, or `:head`).
+  #
   # @param val [String, Symbol] URL to check for version information
   # @return [String, nil]
   def url(val = nil)

Library/Homebrew/livecheck/livecheck.rb

@@ -5,8 +5,8 @@ require "livecheck/strategy"
 require "ruby-progressbar"
 
 module Homebrew
-  # The `Livecheck` module consists of methods used by the `brew livecheck`
-  # command. These methods receive print the requested livecheck information
+  # The {Livecheck} module consists of methods used by the `brew livecheck`
+  # command. These methods print the requested livecheck information
   # for formulae.
   #
   # @api private
@@ -198,8 +198,8 @@ module Homebrew
       puts JSON.generate(formulae_checked.compact)
     end
 
-    # Returns the fully-qualified name of a formula if the full_name argument is
-    # provided, returns the name otherwise.
+    # Returns the fully-qualified name of a formula if the `full_name` argument is
+    # provided; returns the name otherwise.
     # @return [String]
     def formula_name(formula, args:)
       args.full_name? ? formula.full_name : formula.name
@@ -223,7 +223,7 @@ module Homebrew
     end
 
     # If a formula has to be skipped, it prints or returns a Hash contaning the reason
-    # for doing so, else it returns false.
+    # for doing so; returns false otherwise.
     # @return [Hash, nil, Boolean]
     def skip_conditions(formula, args:)
       if formula.deprecated? && !formula.livecheckable?

Library/Homebrew/livecheck/strategy.rb

@@ -19,9 +19,9 @@ module Homebrew
       DEFAULT_PRIORITY = 5
       private_constant :DEFAULT_PRIORITY
 
-      # Creates and/or returns a `@strategies` `Hash` ,which maps a snake
-      # case strategy name symbol (e.g., `:page_match`) to the associated
-      # `Strategy`.
+      # Creates and/or returns a `@strategies` `Hash`, which maps a snake
+      # case strategy name symbol (e.g. `:page_match`) to the associated
+      # {Strategy}.
       #
       # At present, this should only be called after tap strategies have been
       # loaded, otherwise livecheck won't be able to use them.
@@ -39,16 +39,18 @@ module Homebrew
       end
       private_class_method :strategies
 
-      # Returns the `Strategy` that corresponds to the provided `Symbol` (or
-      # `nil` if there is no matching `Strategy`).
+      # Returns the {Strategy} that corresponds to the provided `Symbol` (or
+      # `nil` if there is no matching {Strategy}).
+      #
       # @param symbol [Symbol] the strategy name in snake case as a `Symbol`
-      #   (e.g., `:page_match`)
+      #   (e.g. `:page_match`)
       # @return [Strategy, nil]
       def from_symbol(symbol)
         strategies[symbol]
       end
 
       # Returns an array of strategies that apply to the provided URL.
+      #
       # @param url [String] the URL to check for matching strategies
       # @param regex_provided [Boolean] whether a regex is provided in a
       #   `livecheck` block

Library/Homebrew/livecheck/strategy/apache.rb

@@ -4,17 +4,17 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The `Apache` strategy identifies versions of software at apache.org
+      # The {Apache} strategy identifies versions of software at apache.org
       # by checking directory listing pages.
       #
       # Apache URLs start with `https://www.apache.org/dyn/closer.lua?path=`.
-      #
       # The `path` parameter takes one of the following formats:
+      #
       # * `example/1.2.3/example-1.2.3.tar.gz`
       # * `example/example-1.2.3/example-1.2.3.tar.gz`
       # * `example/example-1.2.3-bin.tar.gz`
       #
-      # When the `path` contains a version directory (e.g., `/1.2.3/`,
+      # When the `path` contains a version directory (e.g. `/1.2.3/`,
       # `/example-1.2.3/`, etc.), the default regex matches numeric versions
       # in directory names. Otherwise, the default regex matches numeric
       # versions in filenames.
@@ -25,6 +25,7 @@ module Homebrew
         URL_MATCH_REGEX = %r{www\.apache\.org/dyn/.+path=.+}i.freeze
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -32,8 +33,8 @@ module Homebrew
         end
 
         # Generates a URL and regex (if one isn't provided) and passes them
-        # to the `PageMatch#find_versions` method to identify versions in the
-        # content.
+        # to {PageMatch.find_versions} to identify versions in the content.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]
@@ -46,7 +47,7 @@ module Homebrew
             (?<suffix>/|[^/]*) # Any text in filename or directory after version
           }ix =~ url
 
-          # Use `\.t` instead of specific tarball extensions (e.g., .tar.gz)
+          # Use `\.t` instead of specific tarball extensions (e.g. .tar.gz)
           suffix.sub!(/\.t(?:ar\..+|[a-z0-9]+)$/i, "\.t")
 
           # Example URL: `https://archive.apache.org/dist/example/`

Library/Homebrew/livecheck/strategy/bitbucket.rb

@@ -4,10 +4,11 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The `Bitbucket` strategy identifies versions of software at
+      # The {Bitbucket} strategy identifies versions of software at
       # bitbucket.org by checking a repository's available downloads.
       #
       # Bitbucket URLs generally take one of the following formats:
+      #
       # * `https://bitbucket.org/example/example/get/1.2.3.tar.gz`
       # * `https://bitbucket.org/example/example/downloads/example-1.2.3.tar.gz`
       #
@@ -31,6 +32,7 @@ module Homebrew
         URL_MATCH_REGEX = %r{bitbucket\.org(/[^/]+){4}\.\w+}i.freeze
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -38,8 +40,8 @@ module Homebrew
         end
 
         # Generates a URL and regex (if one isn't provided) and passes them
-        # to the `PageMatch#find_versions` method to identify versions in the
-        # content.
+        # to {PageMatch.find_versions} to identify versions in the content.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]
@@ -53,7 +55,7 @@ module Homebrew
             (?<suffix>[^/]+) # Filename text after the version
           }ix =~ url
 
-          # Use `\.t` instead of specific tarball extensions (e.g., .tar.gz)
+          # Use `\.t` instead of specific tarball extensions (e.g. .tar.gz)
           suffix.sub!(/\.t(?:ar\..+|[a-z0-9]+)$/i, "\.t")
 
           # `/get/` archives are Git tag snapshots, so we need to check that tab

Library/Homebrew/livecheck/strategy/git.rb

@@ -6,19 +6,19 @@ require "open3"
 module Homebrew
   module Livecheck
     module Strategy
-      # The `Git` strategy identifies versions of software in a Git repository
+      # The {Git} strategy identifies versions of software in a Git repository
       # by checking the tags using `git ls-remote --tags`.
       #
-      # Livecheck has historically prioritized the `Git` strategy over others
+      # Livecheck has historically prioritized the {Git} strategy over others
       # and this behavior was continued when the priority setup was created.
-      # This is partly related to livecheck checking formula URLs in order of
+      # This is partly related to Livecheck checking formula URLs in order of
       # `head`, `stable`, and then `homepage`. The higher priority here may
       # be removed (or altered) in the future if we reevaluate this particular
       # behavior.
       #
       # This strategy does not have a default regex. Instead, it simply removes
       # any non-digit text from the start of tags and parses the rest as a
-      # `Version`. This works for some simple situations but even one unusual
+      # {Version}. This works for some simple situations but even one unusual
       # tag can cause a bad result. It's better to provide a regex in a
       # `livecheck` block, so `livecheck` only matches what we really want.
       #
@@ -31,6 +31,7 @@ module Homebrew
         # Fetches a remote Git repository's tags using `git ls-remote --tags`
         # and parses the command's output. If a regex is provided, it will be
         # used to filter out any tags that don't match it.
+        #
         # @param url [String] the URL of the Git repository to check
         # @param regex [Regexp] the regex to use for filtering tags
         # @return [Hash]
@@ -59,6 +60,7 @@ module Homebrew
         end
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -66,8 +68,9 @@ module Homebrew
         end
 
         # Checks the Git tags for new versions. When a regex isn't provided,
-        # the `Git` strategy simply removes non-digits from the start of tag
-        # strings and parses the remaining text as a `Version`.
+        # this strategy simply removes non-digits from the start of tag
+        # strings and parses the remaining text as a {Version}.
+        #
         # @param url [String] the URL of the Git repository to check
         # @param regex [Regexp] the regex to use for matching versions
         # @return [Hash]

Library/Homebrew/livecheck/strategy/gnome.rb

@@ -4,12 +4,13 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The `Gnome` strategy identifies versions of software at gnome.org by
+      # The {Gnome} strategy identifies versions of software at gnome.org by
       # checking the available downloads found in a project's `cache.json`
       # file.
       #
-      # GNOME URLs generally follow a format like:
-      # `https://download.gnome.org/sources/example/1.2/example-1.2.3.tar.xz`.
+      # GNOME URLs generally follow a standard format:
+      #
+      # * `https://download.gnome.org/sources/example/1.2/example-1.2.3.tar.xz`
       #
       # The default regex restricts matching to filenames containing a version
       # with an even-numbered minor below 90, as these are stable releases.
@@ -22,6 +23,7 @@ module Homebrew
         URL_MATCH_REGEX = /download\.gnome\.org/i.freeze
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -29,8 +31,8 @@ module Homebrew
         end
 
         # Generates a URL and regex (if one isn't provided) and passes them
-        # to the `PageMatch#find_versions` method to identify versions in the
-        # content.
+        # to {PageMatch.find_versions} to identify versions in the content.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]

Library/Homebrew/livecheck/strategy/gnu.rb

@@ -4,21 +4,21 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The `Gnu` strategy identifies versions of software at gnu.org by
+      # The {Gnu} strategy identifies versions of software at gnu.org by
       # checking directory listing pages.
       #
       # GNU URLs use a variety of formats:
       #
-      # Archive file URLs:
-      # * `https://ftp.gnu.org/gnu/example/example-1.2.3.tar.gz`
-      # * `https://ftp.gnu.org/gnu/example/1.2.3/example-1.2.3.tar.gz`
-      #
-      # Homepage URLs:
-      # * `https://www.gnu.org/software/example/`
-      # * `https://example.gnu.org`
+      # * Archive file URLs:
+      #   * `https://ftp.gnu.org/gnu/example/example-1.2.3.tar.gz`
+      #   * `https://ftp.gnu.org/gnu/example/1.2.3/example-1.2.3.tar.gz`
+      # * Homepage URLs:
+      #   * `https://www.gnu.org/software/example/`
+      #   * `https://example.gnu.org`
       #
       # There are other URL formats that this strategy currently doesn't
       # support:
+      #
       # * `https://ftp.gnu.org/non-gnu/example/source/feature/1.2.3/example-1.2.3.tar.gz`
       # * `https://savannah.nongnu.org/download/example/example-1.2.3.tar.gz`
       # * `https://download.savannah.gnu.org/releases/example/example-1.2.3.tar.gz`
@@ -46,6 +46,7 @@ module Homebrew
         ].freeze
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -53,8 +54,8 @@ module Homebrew
         end
 
         # Generates a URL and regex (if one isn't provided) and passes them
-        # to the `PageMatch#find_versions` method to identify versions in the
-        # content.
+        # to {PageMatch.find_versions} to identify versions in the content.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]

Library/Homebrew/livecheck/strategy/hackage.rb

@@ -4,14 +4,15 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The `Hackage` strategy identifies versions of software at
+      # The {Hackage} strategy identifies versions of software at
       # hackage.haskell.org by checking directory listing pages.
       #
       # Hackage URLs take one of the following formats:
+      #
       # * `https://hackage.haskell.org/package/example-1.2.3/example-1.2.3.tar.gz`
       # * `https://downloads.haskell.org/~ghc/8.10.1/ghc-8.10.1-src.tar.xz`
       #
-      # The default regex checks for the latest version an `h3` heading element
+      # The default regex checks for the latest version in an `h3` heading element
       # with a format like `<h3>example-1.2.3/</h3>`.
       #
       # @api public
@@ -20,6 +21,7 @@ module Homebrew
         URL_MATCH_REGEX = /(?:downloads|hackage)\.haskell\.org/i.freeze
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -27,8 +29,8 @@ module Homebrew
         end
 
         # Generates a URL and regex (if one isn't provided) and passes them
-        # to the `PageMatch#find_versions` method to identify versions in the
-        # content.
+        # to {PageMatch.find_versions} to identify versions in the content.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]

Library/Homebrew/livecheck/strategy/launchpad.rb

@@ -4,22 +4,22 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The `Launchpad` strategy identifies versions of software at
+      # The {Launchpad} strategy identifies versions of software at
       # launchpad.net by checking the main page for a project.
       #
       # Launchpad URLs take a variety of formats but all the current formats
       # contain the project name as the first part of the URL path:
+      #
       # * `https://launchpad.net/example/1.2/1.2.3/+download/example-1.2.3.tar.gz`
       # * `https://launchpad.net/example/trunk/1.2.3/+download/example-1.2.3.tar.gz`
       # * `https://code.launchpad.net/example/1.2/1.2.3/+download/example-1.2.3.tar.gz`
       #
       # The default regex identifies the latest version within an HTML element
       # found on the main page for a project:
-      # ```html
-      # <div class="version">
+      #
+      # <pre><div class="version">
       #   Latest version is 1.2.3
-      # </div>
-      # ```
+      # </div></pre>
       #
       # @api public
       class Launchpad
@@ -27,6 +27,7 @@ module Homebrew
         URL_MATCH_REGEX = /launchpad\.net/i.freeze
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -34,8 +35,8 @@ module Homebrew
         end
 
         # Generates a URL and regex (if one isn't provided) and passes them
-        # to the `PageMatch#find_versions` method to identify versions in the
-        # content.
+        # to {PageMatch.find_versions} to identify versions in the content.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]

Library/Homebrew/livecheck/strategy/npm.rb

@@ -4,10 +4,11 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The `npm` strategy identifies versions of software at
+      # The {Npm} strategy identifies versions of software at
       # registry.npmjs.org by checking the listed versions for a package.
       #
       # npm URLs take one of the following formats:
+      #
       # * `https://registry.npmjs.org/example/-/example-1.2.3.tgz`
       # * `https://registry.npmjs.org/@example/example/-/example-1.2.3.tgz`
       #
@@ -22,6 +23,7 @@ module Homebrew
         URL_MATCH_REGEX = /registry\.npmjs\.org/i.freeze
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -29,8 +31,8 @@ module Homebrew
         end
 
         # Generates a URL and regex (if one isn't provided) and passes them
-        # to the `PageMatch#find_versions` method to identify versions in the
-        # content.
+        # to {PageMatch.find_versions} to identify versions in the content.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]

Library/Homebrew/livecheck/strategy/page_match.rb

@@ -6,14 +6,14 @@ require "open-uri"
 module Homebrew
   module Livecheck
     module Strategy
-      # The `PageMatch` strategy fetches content at a URL and scans it for
+      # The {PageMatch} strategy fetches content at a URL and scans it for
       # matching text using the provided regex.
       #
       # This strategy can be used in a `livecheck` block when no specific
-      # strategies apply to a given URL. Though `PageMatch` will technically
+      # strategies apply to a given URL. Though {PageMatch} will technically
       # match any HTTP URL, the strategy also requires a regex to function.
       #
-      # The `PageMatch#find_versions` method is also used within other
+      # The {find_versions} method is also used within other
       # strategies, to handle the process of identifying version text in
       # content.
       #
@@ -22,7 +22,7 @@ module Homebrew
         NICE_NAME = "Page match"
 
         # A priority of zero causes livecheck to skip the strategy. We do this
-        # for `PageMatch` so we can selectively apply the strategy only when a
+        # for PageMatch so we can selectively apply the strategy only when a
         # regex is provided in a `livecheck` block.
         PRIORITY = 0
 
@@ -30,9 +30,9 @@ module Homebrew
         URL_MATCH_REGEX = %r{^https?://}i.freeze
 
         # Whether the strategy can be applied to the provided URL.
-        #
         # PageMatch will technically match any HTTP URL but it's only usable
         # when the formula has a `livecheck` block containing a regex.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -41,6 +41,7 @@ module Homebrew
 
         # Fetches the content at the URL, uses the regex to match text, and
         # returns an array of unique matches.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in the
         #   content
@@ -53,6 +54,7 @@ module Homebrew
 
         # Checks the content at the URL for new versions, using the provided
         # regex for matching.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]

Library/Homebrew/livecheck/strategy/pypi.rb

@@ -4,11 +4,12 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The `Pypi` strategy identifies versions of software at pypi.org by
+      # The {Pypi} strategy identifies versions of software at pypi.org by
       # checking project pages for archive files.
       #
       # PyPI URLs have a standard format but the hexadecimal text between
       # `/packages/` and the filename varies:
+      #
       # * `https://files.pythonhosted.org/packages/<hex>/<hex>/<long_hex>/example-1.2.3.tar.gz`
       #
       # As such, the default regex only targets the filename at the end of the
@@ -22,6 +23,7 @@ module Homebrew
         URL_MATCH_REGEX = /files\.pythonhosted\.org/i.freeze
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -29,8 +31,8 @@ module Homebrew
         end
 
         # Generates a URL and regex (if one isn't provided) and passes them
-        # to the `PageMatch#find_versions` method to identify versions in the
-        # content.
+        # to {PageMatch.find_versions} to identify versions in the content.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]
@@ -41,7 +43,7 @@ module Homebrew
             (?<suffix>\.tar\.[a-z0-9]+|\.[a-z0-9]+)$ # Filename extension
           /ix =~ File.basename(url)
 
-          # Use `\.t` instead of specific tarball extensions (e.g., .tar.gz)
+          # Use `\.t` instead of specific tarball extensions (e.g. .tar.gz)
           suffix.sub!(/\.t(?:ar\..+|[a-z0-9]+)$/i, "\.t")
 
           # It's not technically necessary to have the `#files` fragment at the

Library/Homebrew/livecheck/strategy/sourceforge.rb

@@ -4,16 +4,17 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The `Sourceforge` strategy identifies versions of software at
+      # The {Sourceforge} strategy identifies versions of software at
       # sourceforge.net by checking a project's RSS feed.
       #
       # SourceForge URLs take a few different formats:
-      # * https://downloads.sourceforge.net/project/example/example-1.2.3.tar.gz
-      # * https://svn.code.sf.net/p/example/code/trunk
-      # * :pserver:anonymous:@example.cvs.sourceforge.net:/cvsroot/example
+      #
+      # * `https://downloads.sourceforge.net/project/example/example-1.2.3.tar.gz`
+      # * `https://svn.code.sf.net/p/example/code/trunk`
+      # * `:pserver:anonymous:@example.cvs.sourceforge.net:/cvsroot/example`
       #
       # The RSS feed for a project contains the most recent release archives
-      # and this is fine for most projects but this approach has some
+      # and while this is fine for most projects, this approach has some
       # shortcomings. Some project releases involve so many files that the one
       # we're interested in isn't present in the feed content. Some projects
       # contain additional software and the archive we're interested in is
@@ -22,7 +23,7 @@ module Homebrew
       # Usually we address this situation by adding a `livecheck` block to
       # the formula that checks the page for the relevant directory in the
       # project instead. In this situation, it's necessary to use
-      # `strategy :page_match` to prevent the `Sourceforge` stratgy from
+      # `strategy :page_match` to prevent the {Sourceforge} stratgy from
       # being used.
       #
       # The default regex matches within `url` attributes in the RSS feed
@@ -36,6 +37,7 @@ module Homebrew
         URL_MATCH_REGEX = /(?:sourceforge|sf)\.net/i.freeze
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -43,8 +45,8 @@ module Homebrew
         end
 
         # Generates a URL and regex (if one isn't provided) and passes them
-        # to the `PageMatch#find_versions` method to identify versions in the
-        # content.
+        # to {PageMatch.find_versions} to identify versions in the content.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]

Library/Homebrew/livecheck/strategy/xorg.rb

@@ -6,10 +6,11 @@ require "open-uri"
 module Homebrew
   module Livecheck
     module Strategy
-      # The `Xorg` strategy identifies versions of software at x.org by
+      # The {Xorg} strategy identifies versions of software at x.org by
       # checking directory listing pages.
       #
       # X.Org URLs take one of the following formats, among several others:
+      #
       # * `https://www.x.org/archive/individual/app/example-1.2.3.tar.bz2`
       # * `https://www.x.org/archive/individual/font/example-1.2.3.tar.bz2`
       # * `https://www.x.org/archive/individual/lib/libexample-1.2.3.tar.bz2`
@@ -17,12 +18,13 @@ module Homebrew
       # * `https://www.x.org/pub/individual/doc/example-1.2.3.tar.gz`
       #
       # The notable differences between URLs are as follows:
+      #
       # * `www.x.org` and `ftp.x.org` seem to be interchangeable (we prefer
       #   `www.x.org`).
       # * `/archive/` is the current top-level directory and `/pub/` will
-      #   redirect to the same URL using `/archive/` instead. [The strategy
-      #   handles this replacement to avoid the redirection.]
-      # * The `/individual/` directory contains a number of directories (e.g.,
+      #   redirect to the same URL using `/archive/` instead. (The strategy
+      #   handles this replacement to avoid the redirection.)
+      # * The `/individual/` directory contains a number of directories (e.g.
       #   app, data, doc, driver, font, lib, etc.) which contain a number of
       #   different archive files.
       #
@@ -31,7 +33,7 @@ module Homebrew
       # This prevents livecheck from fetching the same page more than once and
       # also dramatically speeds up these checks. Eventually we hope to
       # implement a more sophisticated page cache that all strategies using
-      # `PageMatch` can use (and we can simplify this strategy accordingly).
+      # {PageMatch} can use (allowing us to simplify this strategy accordingly).
       #
       # The default regex identifies versions in archive files found in `href`
       # attributes.
@@ -51,6 +53,7 @@ module Homebrew
         @page_data = {}
 
         # Whether the strategy can be applied to the provided URL.
+        #
         # @param url [String] the URL to match against
         # @return [Boolean]
         def self.match?(url)
@@ -61,10 +64,11 @@ module Homebrew
         # content at the URL for new versions (using the regex for matching).
         #
         # The behavior in this method for matching text in the content using a
-        # regex is copied and modified from the `PageMatch` strategy, so that
+        # regex is copied and modified from the {PageMatch} strategy, so that
         # we can add some simple page caching. If this behavior is expanded to
-        # apply to all strategies that use `PageMatch` to identify versions,
-        # then the `Xorg` strategy can be brought in line with the others.
+        # apply to all strategies that use {PageMatch} to identify versions,
+        # then this strategy can be brought in line with the others.
+        #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
         # @return [Hash]

Library/Homebrew/locale.rb

@@ -3,11 +3,11 @@
 
 # Representation of a system locale.
 #
-# Used to compare the system language and languages defined using cask `language` stanza.
+# Used to compare the system language and languages defined using the cask `language` stanza.
 #
 # @api private
 class Locale
-  # Error when a string cannot be parsed to a `Locale`.
+  # Error when a string cannot be parsed to a {Locale}.
   class ParserError < StandardError
   end
 

Library/Homebrew/messages.rb

@@ -1,7 +1,7 @@
 # typed: true
 # frozen_string_literal: true
 
-# A Messages object collects messages that may need to be displayed together
+# A {Messages} object collects messages that may need to be displayed together
 # at the end of a multi-step `brew` command run.
 class Messages
   attr_reader :caveats, :formula_count, :install_times

Library/Homebrew/migrator.rb

@@ -51,49 +51,49 @@ class Migrator
     end
   end
 
-  # instance of new name formula
+  # Instance of renamed formula.
   attr_reader :formula
 
-  # old name of the formula
+  # Old name of the formula.
   attr_reader :oldname
 
-  # path to oldname's cellar
+  # Path to oldname's cellar.
   attr_reader :old_cellar
 
-  # path to oldname pin
+  # Path to oldname pin.
   attr_reader :old_pin_record
 
-  # path to oldname opt
+  # Path to oldname opt.
   attr_reader :old_opt_record
 
-  # oldname linked keg
+  # Oldname linked keg.
   attr_reader :old_linked_keg
 
-  # path to oldname's linked keg
+  # Path to oldname's linked keg.
   attr_reader :old_linked_keg_record
 
-  # tabs from oldname kegs
+  # Tabs from oldname kegs.
   attr_reader :old_tabs
 
-  # tap of the old name
+  # Tap of the old name.
   attr_reader :old_tap
 
-  # resolved path to oldname pin
+  # Resolved path to oldname pin.
   attr_reader :old_pin_link_record
 
-  # new name of the formula
+  # New name of the formula.
   attr_reader :newname
 
-  # path to newname cellar according to new name
+  # Path to newname cellar according to new name.
   attr_reader :new_cellar
 
-  # true if new cellar existed at initialization time
+  # True if new cellar existed at initialization time.
   attr_reader :new_cellar_existed
 
-  # path to newname pin
+  # Path to newname pin.
   attr_reader :new_pin_record
 
-  # path to newname keg that will be linked if old_linked_keg isn't nil
+  # Path to newname keg that will be linked if old_linked_keg isn't nil.
   attr_reader :new_linked_keg_record
 
   def self.needs_migration?(formula)
@@ -147,7 +147,7 @@ class Migrator
     @old_pin_link_record = old_pin_record.readlink if @pinned
   end
 
-  # Fix INSTALL_RECEIPTs for tap-migrated formula.
+  # Fix `INSTALL_RECEIPT`s for tap-migrated formula.
   def fix_tabs
     old_tabs.each do |tab|
       tab.tap = formula.tap
@@ -170,7 +170,7 @@ class Migrator
     if formula_tap_user == old_tap_user
       true
     # Homebrew didn't use to update tabs while performing tap-migrations,
-    # so there can be INSTALL_RECEIPTs containing wrong information about tap,
+    # so there can be `INSTALL_RECEIPT`s containing wrong information about tap,
     # so we check if there is an entry about oldname migrated to tap and if
     # newname's tap is the same as tap to which oldname migrated, then we
     # can perform migrations and the taps for oldname and newname are the same.
@@ -226,7 +226,7 @@ class Migrator
     unlock
   end
 
-  # move everything from Cellar/oldname to Cellar/newname
+  # Move everything from `Cellar/oldname` to `Cellar/newname`.
   def move_to_new_directory
     return unless old_cellar.exist?
 
@@ -340,8 +340,8 @@ class Migrator
     old_opt_record.make_relative_symlink(new_linked_keg_record)
   end
 
-  # After migtaion every INSTALL_RECEIPT.json has wrong path to the formula
-  # so we must update INSTALL_RECEIPTs
+  # After migration every `INSTALL_RECEIPT.json` has the wrong path to the formula
+  # so we must update `INSTALL_RECEIPT`s.
   def update_tabs
     new_tabs = new_cellar.subdirs.map { |d| Tab.for_keg(Keg.new(d)) }
     new_tabs.each do |tab|
@@ -350,7 +350,7 @@ class Migrator
     end
   end
 
-  # Remove opt/oldname link if it belongs to newname.
+  # Remove `opt/oldname` link if it belongs to newname.
   def unlink_oldname_opt
     return unless old_opt_record
 
@@ -362,13 +362,13 @@ class Migrator
     end
   end
 
-  # Remove old_cellar if it exists
+  # Remove `Cellar/oldname` if it exists.
   def link_oldname_cellar
     old_cellar.delete if old_cellar.symlink? || old_cellar.exist?
     old_cellar.make_relative_symlink(formula.rack)
   end
 
-  # Remove Cellar/oldname link if it belongs to newname.
+  # Remove `Cellar/oldname` link if it belongs to newname.
   def unlink_oldname_cellar
     if (old_cellar.symlink? && !old_cellar.exist?) || (old_cellar.symlink? \
           && formula.rack.exist? && formula.rack.realpath == old_cellar.realpath)
@@ -376,7 +376,7 @@ class Migrator
     end
   end
 
-  # Backup everything if errors occurred while migrating.
+  # Backup everything if errors occur while migrating.
   def backup_oldname
     unlink_oldname_opt
     unlink_oldname_cellar

Library/Homebrew/mktemp.rb

@@ -1,12 +1,12 @@
 # typed: false
 # frozen_string_literal: true
 
-# Performs `Formula#mktemp`'s functionality, and tracks the results.
+# Performs {Formula#mktemp}'s functionality, and tracks the results.
 # Each instance is only intended to be used once.
 class Mktemp
   include FileUtils
 
-  # Path to the tmpdir used in this run, as a Pathname.
+  # Path to the tmpdir used in this run, as a {Pathname}.
   attr_reader :tmpdir
 
   def initialize(prefix = name, opts = {})
@@ -15,17 +15,17 @@ class Mktemp
     @quiet = false
   end
 
-  # Instructs this Mktemp to retain the staged files
+  # Instructs this {Mktemp} to retain the staged files.
   def retain!
     @retain = true
   end
 
-  # True if the staged temporary files should be retained
+  # True if the staged temporary files should be retained.
   def retain?
     @retain
   end
 
-  # Instructs this Mktemp to not emit messages when retention is triggered
+  # Instructs this Mktemp to not emit messages when retention is triggered.
   def quiet!
     @quiet = true
   end

Library/Homebrew/os/linux/elf.rb

@@ -2,7 +2,6 @@
 # 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

Library/Homebrew/os/linux/global.rb

@@ -1,7 +1,7 @@
 # typed: false
 # frozen_string_literal: true
 
-# enables experimental patchelf.rb write support.
+# Enables experimental `patchelf.rb` write support.
 HOMEBREW_PATCHELF_RB_WRITE = (
   ENV["HOMEBREW_NO_PATCHELF_RB_WRITE"].blank? &&
   (ENV["HOMEBREW_PATCHELF_RB_WRITE"].present? ||

Library/Homebrew/os/mac.rb

@@ -121,7 +121,7 @@ module OS
       sdk(v)
     end
 
-    # Returns the path to an SDK or nil, following the rules set by {.sdk}.
+    # Returns the path to an SDK or nil, following the rules set by {sdk}.
     def sdk_path(v = nil)
       s = sdk(v)
       s&.path

Library/Homebrew/os/mac/sdk.rb

@@ -123,7 +123,7 @@ module OS
 
       # While CLT SDKs existed prior to Xcode 10, those packages also
       # installed a traditional Unix-style header layout and we prefer
-      # using that
+      # using that.
       # As of Xcode 10, the Unix-style headers are installed via a
       # separate package, so we can't rely on their being present.
       # This will only look up SDKs on Xcode 10 or newer, and still

Library/Homebrew/os/mac/version.rb

@@ -48,7 +48,7 @@ module OS
         to_sym.to_s.split("_").map(&:capitalize).join(" ")
       end
 
-      # For OS::Mac::Version compatibility
+      # For {OS::Mac::Version} compatibility.
       def requires_nehalem_cpu?
         unless Hardware::CPU.intel?
           raise "Unexpected architecture: #{Hardware::CPU.arch}. This only works with Intel architecture."

Library/Homebrew/os/mac/xcode.rb

@@ -77,7 +77,7 @@ module OS
       end
 
       # Returns a Pathname object corresponding to Xcode.app's Developer
-      # directory or nil if Xcode.app is not installed
+      # directory or nil if Xcode.app is not installed.
       def prefix
         @prefix ||=
           begin
@@ -215,7 +215,7 @@ module OS
       MAVERICKS_NEW_PKG_ID = "com.apple.pkg.CLTools_Base" # obsolete
       PKG_PATH = "/Library/Developer/CommandLineTools"
 
-      # Returns true even if outdated tools are installed
+      # Returns true even if outdated tools are installed.
       def installed?
         !version.null?
       end
@@ -312,7 +312,7 @@ module OS
       end
 
       # Version string (a pretty long one) of the CLT package.
-      # Note, that different ways to install the CLTs lead to different
+      # Note that the different ways of installing the CLTs lead to different
       # version numbers.
       def version
         if @version ||= detect_version

Library/Homebrew/resource.rb

@@ -20,7 +20,7 @@ class Resource
   attr_accessor :download_strategy, :checksum
 
   # Formula name must be set after the DSL, as we have no access to the
-  # formula name before initialization of the formula
+  # formula name before initialization of the formula.
   attr_accessor :name
 
   def initialize(name = nil, &block)
@@ -45,9 +45,9 @@ class Resource
                                           mirrors: mirrors.dup, **specs)
   end
 
-  # Removes /s from resource names; this allows go package names
+  # Removes /s from resource names; this allows Go package names
   # to be used as resource names without confusing software that
-  # interacts with download_name, e.g. github.com/foo/bar
+  # interacts with {download_name}, e.g. `github.com/foo/bar`.
   def escaped_name
     name.tr("/", "-")
   end
@@ -247,7 +247,7 @@ class Resource
   end
 end
 
-# The context in which a {Resource.stage} occurs. Supports access to both
+# 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.
 #
@@ -255,9 +255,9 @@ end
 class ResourceStageContext
   extend Forwardable
 
-  # The {Resource} that is being staged
+  # The {Resource} that is being staged.
   attr_reader :resource
-  # The {Mktemp} in which {#resource} is staged
+  # The {Mktemp} in which {#resource} is staged.
   attr_reader :staging
 
   def_delegators :@resource, :version, :url, :mirrors, :specs, :using, :source_modified_time

Library/Homebrew/rubocops/cask/constants/stanza.rb

@@ -3,7 +3,7 @@
 
 module RuboCop
   module Cask
-    # Constants available globally for use in all Cask cops.
+    # Constants available globally for use in all cask cops.
     module Constants
       STANZA_GROUPS = [
         [:version, :sha256],

Library/Homebrew/rubocops/cask/desc.rb

@@ -9,8 +9,8 @@ require "rubocops/shared/desc_helper"
 module RuboCop
   module Cop
     module Cask
-      # This cop audits `desc` in Casks.
-      # See the `DescHelper` module for details of the checks.
+      # This cop audits `desc` in casks.
+      # See the {DescHelper} module for details of the checks.
       class Desc < Cop
         include OnDescStanza
         include DescHelper

Library/Homebrew/rubocops/cask/extend/node.rb

@@ -3,7 +3,7 @@
 
 module RuboCop
   module AST
-    # Extensions for RuboCop's AST Node class
+    # Extensions for RuboCop's AST Node class.
     class Node
       include RuboCop::Cask::Constants
 

Library/Homebrew/rubocops/cask/extend/string.rb

@@ -1,7 +1,7 @@
 # typed: true
 # frozen_string_literal: true
 
-# Utility method extensions for String
+# Utility method extensions for String.
 class String
   def undent
     gsub(/^.{#{(slice(/^ +/) || '').length}}/, "")

Library/Homebrew/rubocops/cask/homepage_matches_url.rb

@@ -6,7 +6,7 @@ require "forwardable"
 module RuboCop
   module Cop
     module Cask
-      # This cop checks that a cask's homepage matches the download url,
+      # This cop checks that a cask's homepage matches the download URL,
       # or if it doesn't, checks if a comment in the form
       # `# example.com was verified as official when first introduced to the cask`
       # is present.

Library/Homebrew/rubocops/cask/mixin/cask_help.rb

@@ -4,7 +4,7 @@
 module RuboCop
   module Cop
     module Cask
-      # Common functionality for cops checking casks
+      # Common functionality for cops checking casks.
       module CaskHelp
         def on_block(block_node)
           super if defined? super

Library/Homebrew/rubocops/checksum.rb

@@ -43,7 +43,7 @@ module RuboCop
         end
       end
 
-      # This cop makes sure that checksums strings are lowercase.
+      # This cop makes sure that checksum strings are lowercase.
       #
       # @api private
       class ChecksumCase < FormulaCop

Library/Homebrew/rubocops/class.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop makes sure that `Formula` is used as superclass.
+      # This cop makes sure that {Formula} is used as superclass.
       #
       # @api private
       class ClassName < FormulaCop

Library/Homebrew/rubocops/components_order.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop checks for correct order of components in Formulae.
+      # This cop checks for correct order of components in formulae.
       #
       # - `component_precedence_list` has component hierarchy in a nested list
       #   where each sub array contains components' details which are at same precedence level
@@ -157,7 +157,7 @@ module RuboCop
           end
         end
 
-        # autocorrect method gets called just after component_problem method call
+        # {autocorrect} gets called just after {component_problem}.
         def autocorrect(_node)
           return if @offensive_nodes.nil?
 
@@ -192,7 +192,7 @@ module RuboCop
           corrector.remove(range_with_surrounding_space(range: node1.source_range, side: :left))
         end
 
-        # Returns precedence index and component's index to properly reorder and group during autocorrect
+        # Returns precedence index and component's index to properly reorder and group during autocorrect.
         def get_state(node1)
           @present_components.each_with_index do |comp, idx|
             return [idx, comp.index(node1), comp] if comp.member?(node1)
@@ -228,7 +228,7 @@ module RuboCop
           nil
         end
 
-        # Method to format message for reporting component precedence violations
+        # Method to format message for reporting component precedence violations.
         def component_problem(c1, c2)
           return if COMPONENT_ALLOWLIST.include?(@formula_name)
 
@@ -238,7 +238,7 @@ module RuboCop
         end
 
         # Node pattern method to match
-        # `depends_on` variants
+        # `depends_on` variants.
         def_node_matcher :depends_on_node?, <<~EOS
           {(if _ (send nil? :depends_on ...) nil?)
            (send nil? :depends_on ...)}

Library/Homebrew/rubocops/conflicts.rb

@@ -7,7 +7,7 @@ require "extend/string"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits versioned Formulae for `conflicts_with`.
+      # This cop audits versioned formulae for `conflicts_with`.
       class Conflicts < FormulaCop
         MSG = "Versioned formulae should not use `conflicts_with`. " \
               "Use `keg_only :versioned_formula` instead."

Library/Homebrew/rubocops/dependency_order.rb

@@ -6,10 +6,10 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop checks for correct order of `depends_on` in Formulae.
+      # This cop checks for correct order of `depends_on` in formulae.
       #
       # precedence order:
-      # build-time > run-time > normal > recommended > optional
+      # build-time > test > normal > recommended > optional
       class DependencyOrder < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           check_dependency_nodes_order(body_node)
@@ -61,8 +61,8 @@ module RuboCop
         end
 
         # `depends_on :apple if build.with? "foo"` should always be defined
-        #  after `depends_on :foo`
-        # This method reorders dependencies array according to above rule
+        #  after `depends_on :foo`.
+        # This method reorders the dependencies array according to the above rule.
         def sort_conditional_dependencies!(ordered)
           length = ordered.size
           idx = 0
@@ -86,8 +86,8 @@ module RuboCop
           ordered
         end
 
-        # Verify actual order of sorted `depends_on` nodes in source code
-        # Else raise RuboCop problem
+        # Verify actual order of sorted `depends_on` nodes in source code;
+        # raise RuboCop problem otherwise.
         def verify_order_in_source(ordered)
           ordered.each_with_index do |dependency_node_1, idx|
             l1 = line_number(dependency_node_1)
@@ -104,7 +104,7 @@ module RuboCop
         end
 
         # Node pattern method to match
-        # `depends_on` variants
+        # `depends_on` variants.
         def_node_matcher :depends_on_node?, <<~EOS
           {(if _ (send nil? :depends_on ...) nil?)
            (send nil? :depends_on ...)}
@@ -168,7 +168,7 @@ module RuboCop
                   "\"#{dependency_name(c2)}\" (line #{line_number(c2)})"
         end
 
-        # Reorder two nodes in the source, using the corrector instance in autocorrect method
+        # Reorder two nodes in the source, using the corrector instance in the {autocorrect} method.
         def reorder_components(corrector, node1, node2)
           indentation = " " * (start_column(node2) - line_start_column(node2))
           line_breaks = "\n"

Library/Homebrew/rubocops/deprecate_disable.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits deprecate! date and disable! date
+      # This cop audits `deprecate!` and `disable!` dates.
       class DeprecateDisableDate < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           [:deprecate!, :disable!].each do |method|
@@ -36,7 +36,7 @@ module RuboCop
         EOS
       end
 
-      # This cop audits deprecate! reason
+      # This cop audits `deprecate!` and `disable!` reasons.
       class DeprecateDisableReason < FormulaCop
         PUNCTUATION_MARKS = %w[. ! ?].freeze
 

Library/Homebrew/rubocops/extend/formula.rb

@@ -26,7 +26,7 @@ module RuboCop
 
       @registry = Cop.registry
 
-      # This method is called by RuboCop and is the main entry point
+      # This method is called by RuboCop and is the main entry point.
       def on_class(node)
         @file_path = processed_source.buffer.name
         return unless file_path_allowed?
@@ -39,8 +39,9 @@ module RuboCop
       end
 
       # Yields to block when there is a match.
+      #
       # @param urls [Array] url/mirror method call nodes
-      # @param regex [Regexp] pattern to match urls
+      # @param regex [Regexp] pattern to match URLs
       def audit_urls(urls, regex)
         urls.each do |url_node|
           url_string_node = parameters(url_node).first
@@ -53,7 +54,7 @@ module RuboCop
         end
       end
 
-      # Returns all string nodes among the descendants of given node
+      # Returns all string nodes among the descendants of given node.
       def find_strings(node)
         return [] if node.nil?
         return [node] if node.str_type?
@@ -61,7 +62,7 @@ module RuboCop
         node.each_descendant(:str)
       end
 
-      # Returns method_node matching method_name
+      # Returns method_node matching method_name.
       def find_node_method_by_name(node, method_name)
         return if node.nil?
 
@@ -78,13 +79,13 @@ module RuboCop
         nil
       end
 
-      # Set the given node as the offending node when required in custom cops
+      # Sets the given node as the offending node when required in custom cops.
       def offending_node(node)
         @offensive_node = node
         @offense_source_range = node.source_range
       end
 
-      # Returns an array of method call nodes matching method_name inside node with depth first order (Children nodes)
+      # Returns an array of method call nodes matching method_name inside node with depth first order (child nodes).
       def find_method_calls_by_name(node, method_name)
         return if node.nil?
 
@@ -106,7 +107,7 @@ module RuboCop
       #
       # - matches function call: `foo(*args, **kwargs)`
       # - does not match method calls: `foo.bar(*args, **kwargs)`
-      # - returns every function calls if no func_name is passed
+      # - returns every function call if no func_name is passed
       def find_every_func_call_by_name(node, func_name = nil)
         return if node.nil?
 
@@ -116,7 +117,7 @@ module RuboCop
       end
 
       # Given a method_name and arguments, yields to a block with
-      # matching method passed as a parameter to the block
+      # matching method passed as a parameter to the block.
       def find_method_with_args(node, method_name, *args)
         methods = find_every_method_call_by_name(node, method_name)
         methods.each do |method|
@@ -167,6 +168,7 @@ module RuboCop
       end
 
       # Returns nil if does not depend on dependency_name.
+      #
       # @param dependency_name dependency's name
       def depends_on?(dependency_name, *types)
         types = [:any] if types.empty?
@@ -243,12 +245,12 @@ module RuboCop
         (hash (pair ({str sym} %1) (...)))
       EOS
 
-      # To compare node with appropriate Ruby variable
+      # To compare node with appropriate Ruby variable.
       def node_equals?(node, var)
         node == Parser::CurrentRuby.parse(var.inspect)
       end
 
-      # Returns a block named block_name inside node
+      # Returns a block named block_name inside node.
       def find_block(node, block_name)
         return if node.nil?
 
@@ -265,7 +267,7 @@ module RuboCop
         nil
       end
 
-      # Returns an array of block nodes named block_name inside node
+      # Returns an array of block nodes named block_name inside node.
       def find_blocks(node, block_name)
         return if node.nil?
 
@@ -307,7 +309,7 @@ module RuboCop
         nil
       end
 
-      # Check if a method is called inside a block
+      # Check if a method is called inside a block.
       def method_called_in_block?(node, method_name)
         block_body = node.children[2]
         block_body.each_child_node(:send) do |call_node|
@@ -336,7 +338,7 @@ module RuboCop
         false
       end
 
-      # Check if method_name is called among every descendant node of given node
+      # Check if method_name is called among every descendant node of given node.
       def method_called_ever?(node, method_name)
         node.each_descendant(:send) do |call_node|
           next unless call_node.method_name == method_name
@@ -348,7 +350,7 @@ module RuboCop
         false
       end
 
-      # Checks for precedence, returns the first pair of precedence violating nodes
+      # Checks for precedence; returns the first pair of precedence-violating nodes.
       def check_precedence(first_nodes, next_nodes)
         next_nodes.each do |each_next_node|
           first_nodes.each do |each_first_node|
@@ -358,7 +360,7 @@ module RuboCop
         nil
       end
 
-      # If first node does not precede next_node, sets appropriate instance variables for reporting
+      # If first node does not precede next_node, sets appropriate instance variables for reporting.
       def component_precedes?(first_node, next_node)
         return false if line_number(first_node) < line_number(next_node)
 
@@ -367,7 +369,7 @@ module RuboCop
         true
       end
 
-      # Check if negation is present in the given node
+      # Check if negation is present in the given node.
       def expression_negated?(node)
         return false unless node.parent&.send_type?
         return false unless node.parent.method_name.equal?(:!)
@@ -375,12 +377,12 @@ module RuboCop
         offending_node(node.parent)
       end
 
-      # Return all the caveats' string nodes in an array
+      # Return all the caveats' string nodes in an array.
       def caveats_strings
         find_strings(find_method_def(@body, :caveats))
       end
 
-      # Returns the array of arguments of the method_node
+      # Returns the array of arguments of the method_node.
       def parameters(method_node)
         method_node.arguments if method_node.send_type? || method_node.block_type?
       end
@@ -403,7 +405,7 @@ module RuboCop
         end
       end
 
-      # Returns the sha256 str node given a sha256 call node
+      # Returns the sha256 str node given a sha256 call node.
       def get_checksum_node(call)
         return if parameters(call).empty? || parameters(call).nil?
 
@@ -415,7 +417,7 @@ module RuboCop
         end
       end
 
-      # Yields to a block with comment text as parameter
+      # Yields to a block with comment text as parameter.
       def audit_comments
         @processed_source.comments.each do |comment_node|
           @offensive_node = comment_node
@@ -424,46 +426,46 @@ module RuboCop
         end
       end
 
-      # Returns the ending position of the node in source code
+      # Returns the ending position of the node in source code.
       def end_column(node)
         node.source_range.end_pos
       end
 
-      # Returns the class node's name, nil if not a class node
+      # Returns the class node's name, or nil if not a class node.
       def class_name(node)
         @offensive_node = node
         @offense_source_range = node.source_range
         node.const_name
       end
 
-      # Returns the method name for a def node
+      # Returns the method name for a def node.
       def method_name(node)
         node.children[0] if node.def_type?
       end
 
-      # Returns the node size in the source code
+      # Returns the node size in the source code.
       def size(node)
         node.source_range.size
       end
 
-      # Returns the block length of the block node
+      # Returns the block length of the block node.
       def block_size(block)
         block.loc.end.line - block.loc.begin.line
       end
 
-      # Returns true if the formula is versioned
+      # Returns true if the formula is versioned.
       def versioned_formula?
         @formula_name.include?("@")
       end
 
-      # Returns printable component name
+      # Returns printable component name.
       def format_component(component_node)
         return component_node.method_name if component_node.send_type? || component_node.block_type?
 
         method_name(component_node) if component_node.def_type?
       end
 
-      # Returns the formula tap
+      # Returns the formula tap.
       def formula_tap
         return unless match_obj = @file_path.match(%r{/(homebrew-\w+)/})
 

Library/Homebrew/rubocops/formula_desc.rb

@@ -8,8 +8,8 @@ require "extend/string"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits `desc` in Formulae.
-      # See the `DescHelper` module for details of the checks.
+      # This cop audits `desc` in formulae.
+      # See the {DescHelper} module for details of the checks.
       class Desc < FormulaCop
         include DescHelper
 

Library/Homebrew/rubocops/homepage.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits the `homepage` URL in Formulae.
+      # This cop audits the `homepage` URL in formulae.
       class Homepage < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           homepage_node = find_node_method_by_name(body_node, :homepage)
@@ -23,7 +23,7 @@ module RuboCop
           end
 
           case homepage
-          # Check for http:// GitHub homepage urls, https:// is preferred.
+          # Check for http:// GitHub homepage URLs, https:// is preferred.
           # Note: only check homepages that are repo pages, not *.github.com hosts
           when %r{^http://github.com/}
             problem "Please use https:// for #{homepage}"

Library/Homebrew/rubocops/lines.rb

@@ -110,7 +110,7 @@ module RuboCop
         end
       end
 
-      # This cop makes sure that options are used idiomatically.
+      # This cop makes sure that `option`s are used idiomatically.
       #
       # @api private
       class OptionDeclarations < FormulaCop
@@ -320,7 +320,7 @@ module RuboCop
         EOS
       end
 
-      # This cop makes sure that python versions are consistent.
+      # This cop makes sure that Python versions are consistent.
       #
       # @api private
       class PythonVersions < FormulaCop

Library/Homebrew/rubocops/livecheck.rb

@@ -41,7 +41,7 @@ module RuboCop
         end
       end
 
-      # This cop ensures that a `url` is specified in the livecheck block.
+      # This cop ensures that a `url` is specified in the `livecheck` block.
       #
       # @api private
       class LivecheckUrlProvided < FormulaCop
@@ -124,7 +124,7 @@ module RuboCop
         end
       end
 
-      # This cop ensures that the `regex` call in the livecheck block uses parentheses.
+      # This cop ensures that the `regex` call in the `livecheck` block uses parentheses.
       #
       # @api private
       class LivecheckRegexParentheses < FormulaCop
@@ -188,7 +188,7 @@ module RuboCop
       end
 
       # This cop ensures that a `regex` is provided when `strategy :page_match` is specified
-      # in the livecheck block.
+      # in the `livecheck` block.
       #
       # @api private
       class LivecheckRegexIfPageMatch < FormulaCop

Library/Homebrew/rubocops/options.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits `options` in Formulae.
+      # This cop audits `option`s in formulae.
       class Options < FormulaCop
         DEPRECATION_MSG = "macOS has been 64-bit only since 10.6 so 32-bit options are deprecated."
         UNI_DEPRECATION_MSG = "macOS has been 64-bit only since 10.6 so universal options are deprecated."

Library/Homebrew/rubocops/patches.rb

@@ -7,7 +7,7 @@ require "extend/string"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits patches in Formulae.
+      # This cop audits `patch`es in formulae.
       class Patches < FormulaCop
         def audit_formula(node, _class_node, _parent_class_node, body)
           @full_source_content = source_buffer(node).source

Library/Homebrew/rubocops/shared/desc_helper.rb

@@ -5,7 +5,7 @@ require "rubocops/shared/helper_functions"
 
 module RuboCop
   module Cop
-    # This module performs common checks the `desc` field in both Formulae and Casks.
+    # This module performs common checks the `desc` field in both formulae and casks.
     #
     # @api private
     module DescHelper

Library/Homebrew/rubocops/shared/helper_functions.rb

@@ -10,7 +10,7 @@ module RuboCop
       include RangeHelp
 
       # Checks for regex match of pattern in the node and
-      # sets the appropriate instance variables to report the match
+      # sets the appropriate instance variables to report the match.
       def regex_match_group(node, pattern)
         string_repr = string_content(node).encode("UTF-8", invalid: :replace)
         match_object = string_repr.match(pattern)
@@ -31,27 +31,27 @@ module RuboCop
         match_object
       end
 
-      # Returns the begin position of the node's line in source code
+      # Returns the begin position of the node's line in source code.
       def line_start_column(node)
         node.source_range.source_buffer.line_range(node.loc.line).begin_pos
       end
 
-      # Returns the begin position of the node in source code
+      # Returns the begin position of the node in source code.
       def start_column(node)
         node.source_range.begin_pos
       end
 
-      # Returns the line number of the node
+      # Returns the line number of the node.
       def line_number(node)
         node.loc.line
       end
 
-      # Source buffer is required as an argument to report style violations
+      # Source buffer is required as an argument to report style violations.
       def source_buffer(node)
         node.source_range.source_buffer
       end
 
-      # Returns the string representation if node is of type str(plain) or dstr(interpolated) or const
+      # Returns the string representation if node is of type str(plain) or dstr(interpolated) or const.
       def string_content(node)
         case node.type
         when :str

Library/Homebrew/rubocops/text.rb

@@ -156,7 +156,7 @@ module RuboCop
           end
         end
 
-        # Check whether value starts with the formula name and then a "/", " " or EOS
+        # Check whether value starts with the formula name and then a "/", " " or EOS.
         def path_starts_with?(path, starts_with)
           path.match?(%r{^#{Regexp.escape(starts_with)}(/| |$)})
         end

Library/Homebrew/rubocops/urls.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits URLs and mirrors in Formulae.
+      # This cop audits `url`s and `mirror`s in formulae.
       #
       # @api private
       class Urls < FormulaCop
@@ -55,13 +55,13 @@ module RuboCop
           urls = find_every_func_call_by_name(body_node, :url)
           mirrors = find_every_func_call_by_name(body_node, :mirror)
 
-          # Identify livecheck urls, to skip some checks for them
+          # Identify livecheck URLs, to skip some checks for them
           livecheck_url = if (livecheck = find_every_func_call_by_name(body_node, :livecheck).first) &&
                              (livecheck_url = find_every_func_call_by_name(livecheck.parent, :url).first)
             string_content(parameters(livecheck_url).first)
           end
 
-          # GNU urls; doesn't apply to mirrors
+          # GNU URLs; doesn't apply to mirrors
           gnu_pattern = %r{^(?:https?|ftp)://ftpmirror.gnu.org/(.*)}
           audit_urls(urls, gnu_pattern) do |match, url|
             problem "Please use \"https://ftp.gnu.org/gnu/#{match[1]}\" instead of #{url}."
@@ -202,7 +202,7 @@ module RuboCop
             EOS
           end
 
-          # Check to use canonical urls for Debian packages
+          # Check to use canonical URLs for Debian packages
           noncanon_deb_pattern =
             Regexp.union([%r{^https://mirrors\.kernel\.org/debian/},
                           %r{^https://mirrors\.ocf\.berkeley\.edu/debian/},
@@ -211,26 +211,26 @@ module RuboCop
             problem "Please use https://deb.debian.org/debian/ for #{url}"
           end
 
-          # Check for new-url Google Code download urls, https:// is preferred
+          # Check for new-url Google Code download URLs, https:// is preferred
           google_code_pattern = Regexp.union([%r{^http://.*\.googlecode\.com/files.*},
                                               %r{^http://code\.google\.com/}])
           audit_urls(urls, google_code_pattern) do |_, url|
             problem "Please use https:// for #{url}"
           end
 
-          # Check for git:// GitHub repo urls, https:// is preferred.
+          # Check for git:// GitHub repo URLs, https:// is preferred.
           git_gh_pattern = %r{^git://[^/]*github\.com/}
           audit_urls(urls, git_gh_pattern) do |_, url|
             problem "Please use https:// for #{url}"
           end
 
-          # Check for git:// Gitorious repo urls, https:// is preferred.
+          # Check for git:// Gitorious repo URLs, https:// is preferred.
           git_gitorious_pattern = %r{^git://[^/]*gitorious\.org/}
           audit_urls(urls, git_gitorious_pattern) do |_, url|
             problem "Please use https:// for #{url}"
           end
 
-          # Check for http:// GitHub repo urls, https:// is preferred.
+          # Check for http:// GitHub repo URLs, https:// is preferred.
           gh_pattern = %r{^http://github\.com/.*\.git$}
           audit_urls(urls, gh_pattern) do |_, url|
             problem "Please use https:// for #{url}"
@@ -269,7 +269,7 @@ module RuboCop
             EOS
           end
 
-          # Check for Maven Central urls, prefer HTTPS redirector over specific host
+          # Check for Maven Central URLs, prefer HTTPS redirector over specific host
           maven_pattern = %r{https?://(?:central|repo\d+)\.maven\.org/maven2/(.+)$}
           audit_urls(urls, maven_pattern) do |match, url|
             problem "#{url} should be `https://search.maven.org/remotecontent?filepath=#{match[1]}`"
@@ -290,7 +290,7 @@ module RuboCop
         end
       end
 
-      # This cop makes sure that the correct format for PyPi URLs is used.
+      # This cop makes sure that the correct format for PyPI URLs is used.
       #
       # @api private
       class PyPiUrls < FormulaCop
@@ -299,13 +299,13 @@ module RuboCop
           mirrors = find_every_func_call_by_name(body_node, :mirror)
           urls += mirrors
 
-          # Check pypi urls
+          # Check pypi URLs
           pypi_pattern = %r{^https?://pypi.python.org/}
           audit_urls(urls, pypi_pattern) do |_, url|
             problem "use the `Source` url found on PyPI downloads page (`#{get_pypi_url(url)}`)"
           end
 
-          # Require long files.pythonhosted.org urls
+          # Require long files.pythonhosted.org URLs
           pythonhosted_pattern = %r{^https?://files.pythonhosted.org/packages/source/}
           audit_urls(urls, pythonhosted_pattern) do |_, url|
             problem "use the `Source` url found on PyPI downloads page (`#{get_pypi_url(url)}`)"
@@ -319,7 +319,7 @@ module RuboCop
         end
       end
 
-      # This cop makes sure that git urls have both a `revision`.
+      # This cop makes sure that git URLs have a `revision`.
       #
       # @api private
       class GitUrls < FormulaCop
@@ -342,7 +342,7 @@ module RuboCop
     end
 
     module FormulaAuditStrict
-      # This cop makes sure that git urls have both a `tag`.
+      # This cop makes sure that git URLs have a `tag`.
       #
       # @api private
       class GitUrls < FormulaCop

Library/Homebrew/rubocops/uses_from_macos.rb

@@ -6,11 +6,15 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits `uses_from_macos` dependencies in formulae
+      # This cop audits `uses_from_macos` dependencies in formulae.
       class UsesFromMacos < FormulaCop
         # Generate with:
+        #
+        # ```
         # brew ruby -e 'puts Formula.select {|f| f.keg_only_reason&.provided_by_macos? }.map(&:name).sort.join("\n")'
-        # Not done at runtime as its too slow and RuboCop doesn't have access.
+        # ```
+        #
+        # Not done at runtime as it's too slow and RuboCop doesn't have access.
         PROVIDED_BY_MACOS_FORMULAE = %w[
           apr
           bc
@@ -57,8 +61,8 @@ module RuboCop
           zlib
         ].freeze
 
-        # These formulae aren't keg_only :provided_by_macos but are provided by
-        # macOS (or very similarly e.g. OpenSSL where system provides LibreSSL)
+        # These formulae aren't `keg_only :provided_by_macos` but are provided by
+        # macOS (or very similarly, e.g. OpenSSL where system provides LibreSSL).
         # TODO: consider making some of these keg-only.
         ALLOWED_USES_FROM_MACOS_DEPS = (PROVIDED_BY_MACOS_FORMULAE + %w[
           bash

Library/Homebrew/rubocops/version.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop makes sure that a version is in the correct format.
+      # This cop makes sure that a `version` is in the correct format.
       #
       # @api private
       class Version < FormulaCop

Library/Homebrew/shims/super/cc

@@ -381,8 +381,8 @@ class Cmd
     paths.map! { |path| prefix + path }
   end
 
-  # Unlike path_flags, do not prune non-existent directories.
-  # formula.lib for example does not yet exist, but should not be pruned.
+  # Unlike {path_flags}, do not prune non-existent directories.
+  # `formula.lib` for example does not yet exist, but should not be pruned.
   def rpath_flags(prefix, paths)
     paths.uniq.map { |path| prefix + path }
   end

Library/Homebrew/software_spec.rb

@@ -354,7 +354,7 @@ class BottleSpecification
     cellar == :any || cellar == :any_skip_relocation || cellar == HOMEBREW_CELLAR.to_s
   end
 
-  # Does the {Bottle} this BottleSpecification belongs to need to be relocated?
+  # Does the {Bottle} this {BottleSpecification} belongs to need to be relocated?
   def skip_relocation?
     cellar == :any_skip_relocation
   end