From 3768b7a6e9db659e2747c2c396936c5cfe248d51 Mon Sep 17 00:00:00 2001 From: EricFromCanada Date: Thu, 5 Nov 2020 17:17:03 -0500 Subject: [PATCH] apidoc: update comment wording, punctuation, formatting --- Library/Homebrew/cache_store.rb | 25 ++--- .../cask/artifact/abstract_uninstall.rb | 2 +- Library/Homebrew/cask/artifact/moved.rb | 2 +- Library/Homebrew/cask/cmd/internal_stanza.rb | 2 +- Library/Homebrew/cask/cmd/upgrade.rb | 8 +- Library/Homebrew/cask/dsl.rb | 4 +- Library/Homebrew/cask/dsl/base.rb | 2 +- Library/Homebrew/cask/dsl/caveats.rb | 2 +- Library/Homebrew/cask/installer.rb | 2 +- Library/Homebrew/cask/pkg.rb | 2 +- Library/Homebrew/cask_dependent.rb | 2 +- Library/Homebrew/cleaner.rb | 4 +- Library/Homebrew/cleanup.rb | 2 +- Library/Homebrew/cli/named_args.rb | 2 +- Library/Homebrew/cmd/gist-logs.rb | 2 +- Library/Homebrew/cmd/update-report.rb | 2 +- Library/Homebrew/compat/cli/parser.rb | 2 +- Library/Homebrew/compilers.rb | 4 +- Library/Homebrew/cxxstdlib.rb | 2 +- Library/Homebrew/dependable.rb | 4 +- Library/Homebrew/dependency.rb | 10 +- Library/Homebrew/deprecate_disable.rb | 2 +- Library/Homebrew/description_cache_store.rb | 11 +- Library/Homebrew/dev-cmd/audit.rb | 2 +- Library/Homebrew/dev-cmd/create.rb | 2 +- Library/Homebrew/dev-cmd/pr-pull.rb | 4 +- Library/Homebrew/download_strategy.rb | 2 +- Library/Homebrew/exceptions.rb | 2 +- Library/Homebrew/extend/ENV/shared.rb | 2 +- Library/Homebrew/extend/ENV/super.rb | 10 +- .../Homebrew/extend/os/linux/hardware/cpu.rb | 2 +- .../extend/os/linux/linkage_checker.rb | 1 - .../Homebrew/extend/os/mac/extend/ENV/std.rb | 4 +- .../Homebrew/extend/os/mac/hardware/cpu.rb | 6 +- .../Homebrew/extend/os/mac/keg_relocate.rb | 4 +- Library/Homebrew/extend/pathname.rb | 14 +-- Library/Homebrew/formula.rb | 106 +++++++++--------- Library/Homebrew/formula_assertions.rb | 2 +- Library/Homebrew/formula_info.rb | 2 +- Library/Homebrew/formula_support.rb | 2 +- Library/Homebrew/formulary.rb | 18 ++- Library/Homebrew/keg.rb | 2 +- Library/Homebrew/keg_relocate.rb | 2 +- Library/Homebrew/language/go.rb | 4 +- Library/Homebrew/language/python.rb | 21 ++-- Library/Homebrew/linkage_cache_store.rb | 10 +- Library/Homebrew/linkage_checker.rb | 2 +- Library/Homebrew/livecheck.rb | 14 ++- Library/Homebrew/livecheck/livecheck.rb | 10 +- Library/Homebrew/livecheck/strategy.rb | 14 ++- Library/Homebrew/livecheck/strategy/apache.rb | 13 ++- .../Homebrew/livecheck/strategy/bitbucket.rb | 10 +- Library/Homebrew/livecheck/strategy/git.rb | 15 ++- Library/Homebrew/livecheck/strategy/gnome.rb | 12 +- Library/Homebrew/livecheck/strategy/gnu.rb | 21 ++-- .../Homebrew/livecheck/strategy/hackage.rb | 10 +- .../Homebrew/livecheck/strategy/launchpad.rb | 15 +-- Library/Homebrew/livecheck/strategy/npm.rb | 8 +- .../Homebrew/livecheck/strategy/page_match.rb | 12 +- Library/Homebrew/livecheck/strategy/pypi.rb | 10 +- .../livecheck/strategy/sourceforge.rb | 18 +-- Library/Homebrew/livecheck/strategy/xorg.rb | 20 ++-- Library/Homebrew/locale.rb | 4 +- Library/Homebrew/messages.rb | 2 +- Library/Homebrew/migrator.rb | 48 ++++---- Library/Homebrew/mktemp.rb | 10 +- Library/Homebrew/os/linux/elf.rb | 1 - Library/Homebrew/os/linux/global.rb | 2 +- Library/Homebrew/os/mac.rb | 2 +- Library/Homebrew/os/mac/sdk.rb | 2 +- Library/Homebrew/os/mac/version.rb | 2 +- Library/Homebrew/os/mac/xcode.rb | 6 +- Library/Homebrew/resource.rb | 12 +- .../rubocops/cask/constants/stanza.rb | 2 +- Library/Homebrew/rubocops/cask/desc.rb | 4 +- Library/Homebrew/rubocops/cask/extend/node.rb | 2 +- .../Homebrew/rubocops/cask/extend/string.rb | 2 +- .../rubocops/cask/homepage_matches_url.rb | 2 +- .../Homebrew/rubocops/cask/mixin/cask_help.rb | 2 +- Library/Homebrew/rubocops/checksum.rb | 2 +- Library/Homebrew/rubocops/class.rb | 2 +- Library/Homebrew/rubocops/components_order.rb | 10 +- Library/Homebrew/rubocops/conflicts.rb | 2 +- Library/Homebrew/rubocops/dependency_order.rb | 16 +-- .../Homebrew/rubocops/deprecate_disable.rb | 4 +- Library/Homebrew/rubocops/extend/formula.rb | 58 +++++----- Library/Homebrew/rubocops/formula_desc.rb | 4 +- Library/Homebrew/rubocops/homepage.rb | 4 +- Library/Homebrew/rubocops/lines.rb | 4 +- Library/Homebrew/rubocops/livecheck.rb | 6 +- Library/Homebrew/rubocops/options.rb | 2 +- Library/Homebrew/rubocops/patches.rb | 2 +- .../Homebrew/rubocops/shared/desc_helper.rb | 2 +- .../rubocops/shared/helper_functions.rb | 12 +- Library/Homebrew/rubocops/text.rb | 2 +- Library/Homebrew/rubocops/urls.rb | 28 ++--- Library/Homebrew/rubocops/uses_from_macos.rb | 12 +- Library/Homebrew/rubocops/version.rb | 2 +- Library/Homebrew/shims/super/cc | 4 +- Library/Homebrew/software_spec.rb | 2 +- Library/Homebrew/style.rb | 2 +- Library/Homebrew/system_command.rb | 2 +- Library/Homebrew/tab.rb | 13 +-- Library/Homebrew/tap.rb | 26 ++--- Library/Homebrew/tap_constants.rb | 10 +- Library/Homebrew/test/keg_spec.rb | 4 +- Library/Homebrew/utils.rb | 10 +- Library/Homebrew/utils/bottles.rb | 2 +- Library/Homebrew/utils/gems.rb | 2 +- Library/Homebrew/utils/pypi.rb | 6 +- Library/Homebrew/version.rb | 14 +-- Library/Homebrew/version/null.rb | 2 +- 112 files changed, 471 insertions(+), 435 deletions(-) diff --git a/Library/Homebrew/cache_store.rb b/Library/Homebrew/cache_store.rb index 982f15c482..51c4492529 100644 --- a/Library/Homebrew/cache_store.rb +++ b/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!(*) diff --git a/Library/Homebrew/cask/artifact/abstract_uninstall.rb b/Library/Homebrew/cask/artifact/abstract_uninstall.rb index b0da73866f..baa8467a37 100644 --- a/Library/Homebrew/cask/artifact/abstract_uninstall.rb +++ b/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 diff --git a/Library/Homebrew/cask/artifact/moved.rb b/Library/Homebrew/cask/artifact/moved.rb index 083c612447..6acb7d7827 100644 --- a/Library/Homebrew/cask/artifact/moved.rb +++ b/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 diff --git a/Library/Homebrew/cask/cmd/internal_stanza.rb b/Library/Homebrew/cask/cmd/internal_stanza.rb index 2c473cda1e..95335690e1 100644 --- a/Library/Homebrew/cask/cmd/internal_stanza.rb +++ b/Library/Homebrew/cask/cmd/internal_stanza.rb @@ -13,7 +13,7 @@ module Cask # # brew cask _stanza [ --quiet ] [ --table | --yaml ] [ ... ] # - # 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. # diff --git a/Library/Homebrew/cask/cmd/upgrade.rb b/Library/Homebrew/cask/cmd/upgrade.rb index daf7536894..56bcbd529c 100644 --- a/Library/Homebrew/cask/cmd/upgrade.rb +++ b/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 diff --git a/Library/Homebrew/cask/dsl.rb b/Library/Homebrew/cask/dsl.rb index 6ea0099400..a716b59277 100644 --- a/Library/Homebrew/cask/dsl.rb +++ b/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 diff --git a/Library/Homebrew/cask/dsl/base.rb b/Library/Homebrew/cask/dsl/base.rb index d1a29f61d7..9a91b8381f 100644 --- a/Library/Homebrew/cask/dsl/base.rb +++ b/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 diff --git a/Library/Homebrew/cask/dsl/caveats.rb b/Library/Homebrew/cask/dsl/caveats.rb index 26d8d7fc79..d1b29565d6 100644 --- a/Library/Homebrew/cask/dsl/caveats.rb +++ b/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 diff --git a/Library/Homebrew/cask/installer.rb b/Library/Homebrew/cask/installer.rb index a5a43851b6..f0310a1197 100644 --- a/Library/Homebrew/cask/installer.rb +++ b/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. diff --git a/Library/Homebrew/cask/pkg.rb b/Library/Homebrew/cask/pkg.rb index b5e625e6f4..b56f3ba194 100644 --- a/Library/Homebrew/cask/pkg.rb +++ b/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) diff --git a/Library/Homebrew/cask_dependent.rb b/Library/Homebrew/cask_dependent.rb index 3f38a25fdd..a372401690 100644 --- a/Library/Homebrew/cask_dependent.rb +++ b/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 diff --git a/Library/Homebrew/cleaner.rb b/Library/Homebrew/cleaner.rb index 9cf117c777..070f5cb213 100644 --- a/Library/Homebrew/cleaner.rb +++ b/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! diff --git a/Library/Homebrew/cleanup.rb b/Library/Homebrew/cleanup.rb index 9c53b91726..f23d8989bf 100644 --- a/Library/Homebrew/cleanup.rb +++ b/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? diff --git a/Library/Homebrew/cli/named_args.rb b/Library/Homebrew/cli/named_args.rb index 3537c99014..99ef08e341 100644 --- a/Library/Homebrew/cli/named_args.rb +++ b/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) diff --git a/Library/Homebrew/cmd/gist-logs.rb b/Library/Homebrew/cmd/gist-logs.rb index 0947d43039..7d3064c7e5 100644 --- a/Library/Homebrew/cmd/gist-logs.rb +++ b/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 diff --git a/Library/Homebrew/cmd/update-report.rb b/Library/Homebrew/cmd/update-report.rb index e0a5877b9a..614d2a5785 100644 --- a/Library/Homebrew/cmd/update-report.rb +++ b/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? diff --git a/Library/Homebrew/compat/cli/parser.rb b/Library/Homebrew/compat/cli/parser.rb index c1678d1596..91093f9080 100644 --- a/Library/Homebrew/compat/cli/parser.rb +++ b/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 diff --git a/Library/Homebrew/compilers.rb b/Library/Homebrew/compilers.rb index 50ffe89799..c8a9dfe584 100644 --- a/Library/Homebrew/compilers.rb +++ b/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) diff --git a/Library/Homebrew/cxxstdlib.rb b/Library/Homebrew/cxxstdlib.rb index fad219e565..8750b0c187 100644 --- a/Library/Homebrew/cxxstdlib.rb +++ b/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? diff --git a/Library/Homebrew/dependable.rb b/Library/Homebrew/dependable.rb index 3d036f41d6..f9ebf7d74f 100644 --- a/Library/Homebrew/dependable.rb +++ b/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? diff --git a/Library/Homebrew/dependency.rb b/Library/Homebrew/dependency.rb index c98d46b0e6..99b8a0a1ee 100644 --- a/Library/Homebrew/dependency.rb +++ b/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 diff --git a/Library/Homebrew/deprecate_disable.rb b/Library/Homebrew/deprecate_disable.rb index a1239e0aa8..5f7eec47fd 100644 --- a/Library/Homebrew/deprecate_disable.rb +++ b/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 diff --git a/Library/Homebrew/description_cache_store.rb b/Library/Homebrew/description_cache_store.rb index 4e2d3e7e25..b867f51c09 100644 --- a/Library/Homebrew/description_cache_store.rb +++ b/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] diff --git a/Library/Homebrew/dev-cmd/audit.rb b/Library/Homebrew/dev-cmd/audit.rb index 12661d6a9b..3241da95d3 100644 --- a/Library/Homebrew/dev-cmd/audit.rb +++ b/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 diff --git a/Library/Homebrew/dev-cmd/create.rb b/Library/Homebrew/dev-cmd/create.rb index 1d45047eff..177ba878e8 100644 --- a/Library/Homebrew/dev-cmd/create.rb +++ b/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 diff --git a/Library/Homebrew/dev-cmd/pr-pull.rb b/Library/Homebrew/dev-cmd/pr-pull.rb index 9ff0229c15..56fceff5e2 100644 --- a/Library/Homebrew/dev-cmd/pr-pull.rb +++ b/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 " "}" diff --git a/Library/Homebrew/download_strategy.rb b/Library/Homebrew/download_strategy.rb index 6192391b78..79538bc168 100644 --- a/Library/Homebrew/download_strategy.rb +++ b/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 diff --git a/Library/Homebrew/exceptions.rb b/Library/Homebrew/exceptions.rb index 56c3b15875..f48dfed104 100644 --- a/Library/Homebrew/exceptions.rb +++ b/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 diff --git a/Library/Homebrew/extend/ENV/shared.rb b/Library/Homebrew/extend/ENV/shared.rb index f01db9dc85..ae49480479 100644 --- a/Library/Homebrew/extend/ENV/shared.rb +++ b/Library/Homebrew/extend/ENV/shared.rb @@ -97,7 +97,7 @@ module SharedEnvExtension # This is done automatically for keg-only formulae. # 
ENV.prepend_path "PKG_CONFIG_PATH", "#{Formula["glib"].opt_lib}/pkgconfig"
# 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. # 
ENV.prepend_path "PATH", which("emacs").dirname
def prepend_path(key, path) return if %w[/usr/bin /bin /usr/sbin /sbin].include? path.to_s diff --git a/Library/Homebrew/extend/ENV/super.rb b/Library/Homebrew/extend/ENV/super.rb index b30a714bf6..4057711609 100644 --- a/Library/Homebrew/extend/ENV/super.rb +++ b/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 diff --git a/Library/Homebrew/extend/os/linux/hardware/cpu.rb b/Library/Homebrew/extend/os/linux/hardware/cpu.rb index badc19f507..0ef9c695dc 100644 --- a/Library/Homebrew/extend/os/linux/hardware/cpu.rb +++ b/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 diff --git a/Library/Homebrew/extend/os/linux/linkage_checker.rb b/Library/Homebrew/extend/os/linux/linkage_checker.rb index 7720cc0d2b..6b7d0ea53e 100644 --- a/Library/Homebrew/extend/os/linux/linkage_checker.rb +++ b/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 diff --git a/Library/Homebrew/extend/os/mac/extend/ENV/std.rb b/Library/Homebrew/extend/os/mac/extend/ENV/std.rb index eceb486719..d7419e2ae8 100644 --- a/Library/Homebrew/extend/os/mac/extend/ENV/std.rb +++ b/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 diff --git a/Library/Homebrew/extend/os/mac/hardware/cpu.rb b/Library/Homebrew/extend/os/mac/hardware/cpu.rb index 0038423b36..2d33360382 100644 --- a/Library/Homebrew/extend/os/mac/hardware/cpu.rb +++ b/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? diff --git a/Library/Homebrew/extend/os/mac/keg_relocate.rb b/Library/Homebrew/extend/os/mac/keg_relocate.rb index b55deed223..896bc69c85 100644 --- a/Library/Homebrew/extend/os/mac/keg_relocate.rb +++ b/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 diff --git a/Library/Homebrew/extend/pathname.rb b/Library/Homebrew/extend/pathname.rb index 0bfbb220fc..6c22d6d201 100644 --- a/Library/Homebrew/extend/pathname.rb +++ b/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 diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index c9b3a34bd1..492944f533 100644 --- a/Library/Homebrew/formula.rb +++ b/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 nil, 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. # 
resource("additional_files").stage { bin.install "my/extra/tool" }
# @!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? # 
(share/"concept2").install "ducks.txt"
# - # Install `./example_code/simple/ones` to share/demos + # Install `./example_code/simple/ones` to `share/demos`: # 
(share/"demos").install "example_code/simple/ones"
# - # Install `./example_code/simple/ones` to share/demos/examples + # Install `./example_code/simple/ones` to `share/demos/examples`: # 
(share/"demos").install "example_code/simple/ones" => "examples"
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: # 
elisp.install "contrib/emacs/example-mode.el"
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. # 
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}:
   # 
system "cmake", ".", *std_cmake_args

   #
-  # 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 ` to append to:
+  # use the `args << if ` to append each:
   # 
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.
     #
     # 
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.
     #
     # 
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.
     # 
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).
     # 
# `:build` means this dep is only needed during build.
     # depends_on "cmake" => :build

     # 
# `:recommended` dependencies are built by default.
     # # But a `--without-...` option is generated to opt-out.
     # depends_on "readline" => :recommended

-    # 
# `:optional` dependencies are NOT built by default.
-    # # But a `--with-...` options is generated.
+    # 
# `:optional` dependencies are NOT built by default unless the
+    # # auto-generated `--with-...` option is passed.
     # depends_on "glib" => :optional

     # 
# 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.

-    # 
# Optional and enforce that boost is built with `--with-c++11`.
+    # 
# Optional and enforce that "boost" is built with `--with-c++11`.
     # depends_on "boost" => [:optional, "with-c++11"]

     # 
# 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).
     # 
option "with-spam", "The description goes here without a dot at the end"

-    # 
option "with-qt", "Text here overwrites the autogenerated one from 'depends_on "qt" => :optional'"

+    # 
option "with-qt", "Text here overwrites what's autogenerated by 'depends_on "qt" => :optional'"

     # 
option :universal

     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.
     #
     # 
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
diff --git a/Library/Homebrew/formula_assertions.rb b/Library/Homebrew/formula_assertions.rb
index 05948f3a2b..2ab9bfc036 100644
--- a/Library/Homebrew/formula_assertions.rb
+++ b/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
diff --git a/Library/Homebrew/formula_info.rb b/Library/Homebrew/formula_info.rb
index 367f7e6947..ad8035172b 100644
--- a/Library/Homebrew/formula_info.rb
+++ b/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)
diff --git a/Library/Homebrew/formula_support.rb b/Library/Homebrew/formula_support.rb
index 67569587f5..287ffd0f0c 100644
--- a/Library/Homebrew/formula_support.rb
+++ b/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
diff --git a/Library/Homebrew/formulary.rb b/Library/Homebrew/formulary.rb
index 2c3689f9a6..3be8bbd3ef 100644
--- a/Library/Homebrew/formulary.rb
+++ b/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)
diff --git a/Library/Homebrew/keg.rb b/Library/Homebrew/keg.rb
index 1036b417ec..d46d0dc67e 100644
--- a/Library/Homebrew/keg.rb
+++ b/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[
diff --git a/Library/Homebrew/keg_relocate.rb b/Library/Homebrew/keg_relocate.rb
index b26b5a7709..6fd598cfa1 100644
--- a/Library/Homebrew/keg_relocate.rb
+++ b/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
diff --git a/Library/Homebrew/language/go.rb b/Library/Homebrew/language/go.rb
index 22f851472b..ecf3465d76 100644
--- a/Library/Homebrew/language/go.rb
+++ b/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?
diff --git a/Library/Homebrew/language/python.rb b/Library/Homebrew/language/python.rb
index 7671b840b3..a60343a704 100644
--- a/Library/Homebrew/language/python.rb
+++ b/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] (A) token(s) passed to pip
+        #   Array] (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)
diff --git a/Library/Homebrew/linkage_cache_store.rb b/Library/Homebrew/linkage_cache_store.rb
index 90f2bccdb1..45bb9bc3d0 100644
--- a/Library/Homebrew/linkage_cache_store.rb
+++ b/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!
diff --git a/Library/Homebrew/linkage_checker.rb b/Library/Homebrew/linkage_checker.rb
index 74bcc6b2ab..67ab46e093 100644
--- a/Library/Homebrew/linkage_checker.rb
+++ b/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?
 
diff --git a/Library/Homebrew/livecheck.rb b/Library/Homebrew/livecheck.rb
index df31c5f455..651d758946 100644
--- a/Library/Homebrew/livecheck.rb
+++ b/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)
diff --git a/Library/Homebrew/livecheck/livecheck.rb b/Library/Homebrew/livecheck/livecheck.rb
index 466dd95e09..7e90808ea8 100644
--- a/Library/Homebrew/livecheck/livecheck.rb
+++ b/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?
diff --git a/Library/Homebrew/livecheck/strategy.rb b/Library/Homebrew/livecheck/strategy.rb
index 4111365455..766512e08f 100644
--- a/Library/Homebrew/livecheck/strategy.rb
+++ b/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
diff --git a/Library/Homebrew/livecheck/strategy/apache.rb b/Library/Homebrew/livecheck/strategy/apache.rb
index 52beb1686f..194cb25266 100644
--- a/Library/Homebrew/livecheck/strategy/apache.rb
+++ b/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
             (?/|[^/]*) # 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/`
diff --git a/Library/Homebrew/livecheck/strategy/bitbucket.rb b/Library/Homebrew/livecheck/strategy/bitbucket.rb
index a1e29a544b..e37690ba6d 100644
--- a/Library/Homebrew/livecheck/strategy/bitbucket.rb
+++ b/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
             (?[^/]+) # 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
diff --git a/Library/Homebrew/livecheck/strategy/git.rb b/Library/Homebrew/livecheck/strategy/git.rb
index 5a1e5edb15..4cd216bf58 100644
--- a/Library/Homebrew/livecheck/strategy/git.rb
+++ b/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]
diff --git a/Library/Homebrew/livecheck/strategy/gnome.rb b/Library/Homebrew/livecheck/strategy/gnome.rb
index fa1e952300..9432015a61 100644
--- a/Library/Homebrew/livecheck/strategy/gnome.rb
+++ b/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]
diff --git a/Library/Homebrew/livecheck/strategy/gnu.rb b/Library/Homebrew/livecheck/strategy/gnu.rb
index 72dbe47771..083330b564 100644
--- a/Library/Homebrew/livecheck/strategy/gnu.rb
+++ b/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]
diff --git a/Library/Homebrew/livecheck/strategy/hackage.rb b/Library/Homebrew/livecheck/strategy/hackage.rb
index 2c2ecd69bc..cc18af6e63 100644
--- a/Library/Homebrew/livecheck/strategy/hackage.rb
+++ b/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 `
example-1.2.3/
`.
       #
       # @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]
diff --git a/Library/Homebrew/livecheck/strategy/launchpad.rb b/Library/Homebrew/livecheck/strategy/launchpad.rb
index c38d393f28..8a820cf8aa 100644
--- a/Library/Homebrew/livecheck/strategy/launchpad.rb
+++ b/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
-      # 

+      #
+      # 

       #   Latest version is 1.2.3
-      # 

-      # ```
+      # 

       #
       # @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]
diff --git a/Library/Homebrew/livecheck/strategy/npm.rb b/Library/Homebrew/livecheck/strategy/npm.rb
index 3c661f155c..3edeec0aab 100644
--- a/Library/Homebrew/livecheck/strategy/npm.rb
+++ b/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]
diff --git a/Library/Homebrew/livecheck/strategy/page_match.rb b/Library/Homebrew/livecheck/strategy/page_match.rb
index 73c80beacd..230060a64d 100644
--- a/Library/Homebrew/livecheck/strategy/page_match.rb
+++ b/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]
diff --git a/Library/Homebrew/livecheck/strategy/pypi.rb b/Library/Homebrew/livecheck/strategy/pypi.rb
index 6fa15dbff6..5132b7b530 100644
--- a/Library/Homebrew/livecheck/strategy/pypi.rb
+++ b/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////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
             (?\.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
diff --git a/Library/Homebrew/livecheck/strategy/sourceforge.rb b/Library/Homebrew/livecheck/strategy/sourceforge.rb
index 88c40d5c24..f8e39620ef 100644
--- a/Library/Homebrew/livecheck/strategy/sourceforge.rb
+++ b/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]
diff --git a/Library/Homebrew/livecheck/strategy/xorg.rb b/Library/Homebrew/livecheck/strategy/xorg.rb
index 5517897b14..657085092a 100644
--- a/Library/Homebrew/livecheck/strategy/xorg.rb
+++ b/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]
diff --git a/Library/Homebrew/locale.rb b/Library/Homebrew/locale.rb
index 278bb621db..7a9ee544ca 100644
--- a/Library/Homebrew/locale.rb
+++ b/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
 
diff --git a/Library/Homebrew/messages.rb b/Library/Homebrew/messages.rb
index bc8c64b501..fee41654da 100644
--- a/Library/Homebrew/messages.rb
+++ b/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
diff --git a/Library/Homebrew/migrator.rb b/Library/Homebrew/migrator.rb
index c60bf82615..4713960d24 100644
--- a/Library/Homebrew/migrator.rb
+++ b/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
diff --git a/Library/Homebrew/mktemp.rb b/Library/Homebrew/mktemp.rb
index 749b8a2157..5b7704d97e 100644
--- a/Library/Homebrew/mktemp.rb
+++ b/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
diff --git a/Library/Homebrew/os/linux/elf.rb b/Library/Homebrew/os/linux/elf.rb
index c38fed883d..e8009af519 100644
--- a/Library/Homebrew/os/linux/elf.rb
+++ b/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
diff --git a/Library/Homebrew/os/linux/global.rb b/Library/Homebrew/os/linux/global.rb
index df09e17ca1..370fa38ed2 100644
--- a/Library/Homebrew/os/linux/global.rb
+++ b/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? ||
diff --git a/Library/Homebrew/os/mac.rb b/Library/Homebrew/os/mac.rb
index bda5e58f2e..c7cd7e1820 100644
--- a/Library/Homebrew/os/mac.rb
+++ b/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
diff --git a/Library/Homebrew/os/mac/sdk.rb b/Library/Homebrew/os/mac/sdk.rb
index 27ccb9d4bf..d67aef5ccf 100644
--- a/Library/Homebrew/os/mac/sdk.rb
+++ b/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
diff --git a/Library/Homebrew/os/mac/version.rb b/Library/Homebrew/os/mac/version.rb
index c8a899cc45..bdda425aa6 100644
--- a/Library/Homebrew/os/mac/version.rb
+++ b/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."
diff --git a/Library/Homebrew/os/mac/xcode.rb b/Library/Homebrew/os/mac/xcode.rb
index 4a276441fb..3714b5a359 100644
--- a/Library/Homebrew/os/mac/xcode.rb
+++ b/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
diff --git a/Library/Homebrew/resource.rb b/Library/Homebrew/resource.rb
index 29655d120a..f9c536467c 100644
--- a/Library/Homebrew/resource.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/cask/constants/stanza.rb b/Library/Homebrew/rubocops/cask/constants/stanza.rb
index 3b818ac900..d5e23b10c8 100644
--- a/Library/Homebrew/rubocops/cask/constants/stanza.rb
+++ b/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],
diff --git a/Library/Homebrew/rubocops/cask/desc.rb b/Library/Homebrew/rubocops/cask/desc.rb
index 0e03da6265..98b6c6bbad 100644
--- a/Library/Homebrew/rubocops/cask/desc.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/cask/extend/node.rb b/Library/Homebrew/rubocops/cask/extend/node.rb
index e0102bd9d1..906518db49 100644
--- a/Library/Homebrew/rubocops/cask/extend/node.rb
+++ b/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
 
diff --git a/Library/Homebrew/rubocops/cask/extend/string.rb b/Library/Homebrew/rubocops/cask/extend/string.rb
index 6dcccff830..e89bed3af4 100644
--- a/Library/Homebrew/rubocops/cask/extend/string.rb
+++ b/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}}/, "")
diff --git a/Library/Homebrew/rubocops/cask/homepage_matches_url.rb b/Library/Homebrew/rubocops/cask/homepage_matches_url.rb
index 3c12c14ac1..1f3c5e6679 100644
--- a/Library/Homebrew/rubocops/cask/homepage_matches_url.rb
+++ b/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.
diff --git a/Library/Homebrew/rubocops/cask/mixin/cask_help.rb b/Library/Homebrew/rubocops/cask/mixin/cask_help.rb
index aa2d6eab14..192e72c99c 100644
--- a/Library/Homebrew/rubocops/cask/mixin/cask_help.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/checksum.rb b/Library/Homebrew/rubocops/checksum.rb
index 35edda879d..2078dfbe5a 100644
--- a/Library/Homebrew/rubocops/checksum.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/class.rb b/Library/Homebrew/rubocops/class.rb
index d44e759673..4a2a408ac8 100644
--- a/Library/Homebrew/rubocops/class.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/components_order.rb b/Library/Homebrew/rubocops/components_order.rb
index 41b35478f0..f76351fc0e 100644
--- a/Library/Homebrew/rubocops/components_order.rb
+++ b/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 ...)}
diff --git a/Library/Homebrew/rubocops/conflicts.rb b/Library/Homebrew/rubocops/conflicts.rb
index f11a9a870f..7a24be5ce1 100644
--- a/Library/Homebrew/rubocops/conflicts.rb
+++ b/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."
diff --git a/Library/Homebrew/rubocops/dependency_order.rb b/Library/Homebrew/rubocops/dependency_order.rb
index fb77e88d56..79943949a8 100644
--- a/Library/Homebrew/rubocops/dependency_order.rb
+++ b/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"
diff --git a/Library/Homebrew/rubocops/deprecate_disable.rb b/Library/Homebrew/rubocops/deprecate_disable.rb
index f077a2b372..a073092ef1 100644
--- a/Library/Homebrew/rubocops/deprecate_disable.rb
+++ b/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
 
diff --git a/Library/Homebrew/rubocops/extend/formula.rb b/Library/Homebrew/rubocops/extend/formula.rb
index 2c7c3e449b..45e23a1b95 100644
--- a/Library/Homebrew/rubocops/extend/formula.rb
+++ b/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+)/})
 
diff --git a/Library/Homebrew/rubocops/formula_desc.rb b/Library/Homebrew/rubocops/formula_desc.rb
index f839e5571b..7ce26eec6b 100644
--- a/Library/Homebrew/rubocops/formula_desc.rb
+++ b/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
 
diff --git a/Library/Homebrew/rubocops/homepage.rb b/Library/Homebrew/rubocops/homepage.rb
index d1e3b06d11..c8f802a2c1 100644
--- a/Library/Homebrew/rubocops/homepage.rb
+++ b/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}"
diff --git a/Library/Homebrew/rubocops/lines.rb b/Library/Homebrew/rubocops/lines.rb
index 6705042323..17a631d6f5 100644
--- a/Library/Homebrew/rubocops/lines.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/livecheck.rb b/Library/Homebrew/rubocops/livecheck.rb
index c7f21adb2a..f7e3bc55c4 100644
--- a/Library/Homebrew/rubocops/livecheck.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/options.rb b/Library/Homebrew/rubocops/options.rb
index f971548bd6..eb7f5d25b8 100644
--- a/Library/Homebrew/rubocops/options.rb
+++ b/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."
diff --git a/Library/Homebrew/rubocops/patches.rb b/Library/Homebrew/rubocops/patches.rb
index 2d893f7d15..8d85bd9f93 100644
--- a/Library/Homebrew/rubocops/patches.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/shared/desc_helper.rb b/Library/Homebrew/rubocops/shared/desc_helper.rb
index a3beae3e70..53300c906c 100644
--- a/Library/Homebrew/rubocops/shared/desc_helper.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/shared/helper_functions.rb b/Library/Homebrew/rubocops/shared/helper_functions.rb
index 5fc65ced98..326f477547 100644
--- a/Library/Homebrew/rubocops/shared/helper_functions.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/text.rb b/Library/Homebrew/rubocops/text.rb
index 30417d0edd..5ace971a75 100644
--- a/Library/Homebrew/rubocops/text.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/urls.rb b/Library/Homebrew/rubocops/urls.rb
index 4ac551b5a5..3c7b855da0 100644
--- a/Library/Homebrew/rubocops/urls.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/uses_from_macos.rb b/Library/Homebrew/rubocops/uses_from_macos.rb
index e164640615..77804e677b 100644
--- a/Library/Homebrew/rubocops/uses_from_macos.rb
+++ b/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
diff --git a/Library/Homebrew/rubocops/version.rb b/Library/Homebrew/rubocops/version.rb
index 2b6b53c011..a6afb74449 100644
--- a/Library/Homebrew/rubocops/version.rb
+++ b/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
diff --git a/Library/Homebrew/shims/super/cc b/Library/Homebrew/shims/super/cc
index 4462deae26..30d249a096 100755
--- a/Library/Homebrew/shims/super/cc
+++ b/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
diff --git a/Library/Homebrew/software_spec.rb b/Library/Homebrew/software_spec.rb
index d35d145c55..8a6ed260e6 100644
--- a/Library/Homebrew/software_spec.rb
+++ b/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
diff --git a/Library/Homebrew/style.rb b/Library/Homebrew/style.rb
index 437df8a775..40a11b50cf 100644
--- a/Library/Homebrew/style.rb
+++ b/Library/Homebrew/style.rb
@@ -30,7 +30,7 @@ module Homebrew
       success
     end
 
-    # Checks style for a list of files, returning results as `Offenses`
+    # Checks style for a list of files, returning results as an {Offenses}
     # object parsed from its JSON output.
     def check_style_json(files, **options)
       check_style_impl(files, :json, **options)
diff --git a/Library/Homebrew/system_command.rb b/Library/Homebrew/system_command.rb
index 8ad098df1a..5a762fe313 100644
--- a/Library/Homebrew/system_command.rb
+++ b/Library/Homebrew/system_command.rb
@@ -15,7 +15,7 @@ using HashValidator
 #
 # @api private
 class SystemCommand
-  # Helper functions for calling `SystemCommand.run`.
+  # Helper functions for calling {SystemCommand.run}.
   module Mixin
     def system_command(*args)
       SystemCommand.run(*args)
diff --git a/Library/Homebrew/tab.rb b/Library/Homebrew/tab.rb
index d1bf8fc241..5cc7e5e789 100644
--- a/Library/Homebrew/tab.rb
+++ b/Library/Homebrew/tab.rb
@@ -9,9 +9,8 @@ require "development_tools"
 require "extend/cachable"
 
 # Inherit from OpenStruct to gain a generic initialization method that takes a
-# hash and creates an attribute for each key and value. `Tab.new` probably
-# should not be called directly, instead use one of the class methods like
-# `Tab.create`.
+# hash and creates an attribute for each key and value. Rather than calling
+# `new` directly, use one of the class methods like {Tab.create}.
 class Tab < OpenStruct
   extend Cachable
 
@@ -54,13 +53,13 @@ class Tab < OpenStruct
     new(attributes)
   end
 
-  # Returns the Tab for an install receipt at `path`.
+  # Returns the {Tab} for an install receipt at `path`.
   # Results are cached.
   def self.from_file(path)
     cache.fetch(path) { |p| cache[p] = from_file_content(File.read(p), p) }
   end
 
-  # Like Tab.from_file, but bypass the cache.
+  # Like {from_file}, but bypass the cache.
   def self.from_file_content(content, path)
     attributes = begin
       JSON.parse(content)
@@ -114,7 +113,7 @@ class Tab < OpenStruct
     tab
   end
 
-  # Returns a tab for the named formula's installation,
+  # Returns a {Tab} for the named formula's installation,
   # or a fake one if the formula is not installed.
   def self.for_name(name)
     for_formula(Formulary.factory(name))
@@ -131,7 +130,7 @@ class Tab < OpenStruct
     options
   end
 
-  # Returns a Tab for an already installed formula,
+  # Returns a {Tab} for an already installed formula,
   # or a fake one if the formula is not installed.
   def self.for_formula(f)
     paths = []
diff --git a/Library/Homebrew/tap.rb b/Library/Homebrew/tap.rb
index 8c6fb892d7..10076bee21 100644
--- a/Library/Homebrew/tap.rb
+++ b/Library/Homebrew/tap.rb
@@ -6,11 +6,11 @@ require "extend/cachable"
 require "description_cache_store"
 
 # A {Tap} is used to extend the formulae provided by Homebrew core.
-# Usually, it's synced with a remote git repository. And it's likely
+# Usually, it's synced with a remote Git repository. And it's likely
 # a GitHub repository with the name of `user/homebrew-repo`. In such
-# case, `user/repo` will be used as the {#name} of this {Tap}, where
-# {#user} represents GitHub username and {#repo} represents repository
-# name without leading `homebrew-`.
+# cases, `user/repo` will be used as the {#name} of this {Tap}, where
+# {#user} represents the GitHub username and {#repo} represents the repository
+# name without the leading `homebrew-`.
 class Tap
   extend Cachable
 
@@ -54,7 +54,7 @@ class Tap
   # this {Tap}'s remote repository.
   attr_reader :user
 
-  # The repository name of this {Tap} without leading `homebrew-`.
+  # The repository name of this {Tap} without the leading `homebrew-`.
   attr_reader :repo
 
   # The name of this {Tap}. It combines {#user} and {#repo} with a slash.
@@ -83,7 +83,7 @@ class Tap
     @alias_reverse_table = nil
   end
 
-  # Clear internal cache
+  # Clear internal cache.
   def clear_cache
     @remote = nil
     @repo_var = nil
@@ -123,7 +123,7 @@ class Tap
                       .upcase
   end
 
-  # True if this {Tap} is a git repository.
+  # True if this {Tap} is a Git repository.
   def git?
     path.git?
   end
@@ -149,14 +149,14 @@ class Tap
     path.git_short_head
   end
 
-  # Time since git last commit for this {Tap}.
+  # Time since last git commit for this {Tap}.
   def git_last_commit
     raise TapUnavailableError, name unless installed?
 
     path.git_last_commit
   end
 
-  # git last commit date for this {Tap}.
+  # Last git commit date for this {Tap}.
   def git_last_commit_date
     raise TapUnavailableError, name unless installed?
 
@@ -196,7 +196,7 @@ class Tap
     @private = read_or_set_private_config
   end
 
-  # {TapConfig} of this {Tap}
+  # {TapConfig} of this {Tap}.
   def config
     @config ||= begin
       raise TapUnavailableError, name unless installed?
@@ -523,7 +523,7 @@ class Tap
     hash
   end
 
-  # Hash with tap formula renames
+  # Hash with tap formula renames.
   def formula_renames
     require "json"
 
@@ -534,7 +534,7 @@ class Tap
     end
   end
 
-  # Hash with tap migrations
+  # Hash with tap migrations.
   def tap_migrations
     require "json"
 
@@ -567,7 +567,7 @@ class Tap
     map(&:name).sort
   end
 
-  # An array of all tap cmd directory {Pathname}s
+  # An array of all tap cmd directory {Pathname}s.
   def self.cmd_directories
     Pathname.glob TAP_DIRECTORY/"*/*/cmd"
   end
diff --git a/Library/Homebrew/tap_constants.rb b/Library/Homebrew/tap_constants.rb
index 1da9c0e571..aa187c838b 100644
--- a/Library/Homebrew/tap_constants.rb
+++ b/Library/Homebrew/tap_constants.rb
@@ -1,14 +1,14 @@
 # typed: true
 # frozen_string_literal: true
 
-# match taps' formulae, e.g. someuser/sometap/someformula
+# Match taps' formulae, e.g. `someuser/sometap/someformula`
 HOMEBREW_TAP_FORMULA_REGEX = %r{^([\w-]+)/([\w-]+)/([\w+-.@]+)$}.freeze
-# match taps' casks, e.g. someuser/sometap/somecask
+# Match taps' casks, e.g. `someuser/sometap/somecask`
 HOMEBREW_TAP_CASK_REGEX = %r{^([\w-]+)/([\w-]+)/([a-z0-9\-]+)$}.freeze
-# match taps' directory paths, e.g. HOMEBREW_LIBRARY/Taps/someuser/sometap
+# Match taps' directory paths, e.g. `HOMEBREW_LIBRARY/Taps/someuser/sometap`
 HOMEBREW_TAP_DIR_REGEX = %r{#{Regexp.escape(HOMEBREW_LIBRARY)}/Taps/(?[\w-]+)/(?[\w-]+)}.freeze
-# match taps' formula paths, e.g. HOMEBREW_LIBRARY/Taps/someuser/sometap/someformula
+# Match taps' formula paths, e.g. `HOMEBREW_LIBRARY/Taps/someuser/sometap/someformula`
 HOMEBREW_TAP_PATH_REGEX = Regexp.new(HOMEBREW_TAP_DIR_REGEX.source + %r{(?:/.*)?$}.source).freeze
-# match official taps' casks, e.g. homebrew/cask/somecask or homebrew/cask-versions/somecask
+# Match official taps' casks, e.g. `homebrew/cask/somecask or homebrew/cask-versions/somecask`
 HOMEBREW_CASK_TAP_CASK_REGEX = %r{^(?:([Cc]askroom)/(cask|versions)|(homebrew)/(cask|cask-[\w-]+))/([\w+-.]+)$}.freeze
 HOMEBREW_OFFICIAL_REPO_PREFIXES_REGEX = /^(home|linux)brew-/.freeze
diff --git a/Library/Homebrew/test/keg_spec.rb b/Library/Homebrew/test/keg_spec.rb
index 73e87d6c9a..c64d825987 100644
--- a/Library/Homebrew/test/keg_spec.rb
+++ b/Library/Homebrew/test/keg_spec.rb
@@ -351,7 +351,7 @@ describe Keg do
     end
 
     # 1.1.6 is the earliest version of Homebrew that generates correct runtime
-    # dependency lists in Tabs.
+    # dependency lists in {Tab}s.
     def dependencies(deps, homebrew_version: "1.1.6")
       alter_tab do |tab|
         tab.homebrew_version = homebrew_version
@@ -362,7 +362,7 @@ describe Keg do
 
     def unreliable_dependencies(deps)
       # 1.1.5 is (hopefully!) the last version of Homebrew that generates
-      # incorrect runtime dependency lists in Tabs.
+      # incorrect runtime dependency lists in {Tab}s.
       dependencies(deps, homebrew_version: "1.1.5")
     end
 
diff --git a/Library/Homebrew/utils.rb b/Library/Homebrew/utils.rb
index 66ceee8919..45f46f3962 100644
--- a/Library/Homebrew/utils.rb
+++ b/Library/Homebrew/utils.rb
@@ -130,13 +130,14 @@ module Kernel
     puts Formatter.headline(title, color: :green)
   end
 
-  # Print a warning (do this rarely)
+  # Print a message prefixed with "Warning" (do this rarely).
   def opoo(message)
     Tty.with($stderr) do |stderr|
       stderr.puts Formatter.warning(message, label: "Warning")
     end
   end
 
+  # Print a message prefixed with "Error".
   def onoe(message)
     Tty.with($stderr) do |stderr|
       stderr.puts Formatter.error(message, label: "Error")
@@ -281,14 +282,14 @@ module Kernel
     with_env(LC_ALL: locale, &block)
   end
 
-  # Kernel.system but with exceptions
+  # Kernel.system but with exceptions.
   def safe_system(cmd, *args, **options)
     return if Homebrew.system(cmd, *args, **options)
 
     raise ErrorDuringExecution.new([cmd, *args], status: $CHILD_STATUS)
   end
 
-  # Prints no output
+  # Prints no output.
   def quiet_system(cmd, *args)
     Homebrew._system(cmd, *args) do
       # Redirect output streams to `/dev/null` instead of closing as some programs
@@ -359,7 +360,7 @@ module Kernel
     safe_system(browser, *args)
   end
 
-  # GZips the given paths, and returns the gzipped paths
+  # GZips the given paths, and returns the gzipped paths.
   def gzip(*paths)
     paths.map do |path|
       safe_system "gzip", path
@@ -477,7 +478,6 @@ module Kernel
 
   # Calls the given block with the passed environment variables
   # added to ENV, then restores ENV afterwards.
-  # Example:
   # 
with_env(PATH: "/bin") do
   #   system "echo $PATH"
   # end

diff --git a/Library/Homebrew/utils/bottles.rb b/Library/Homebrew/utils/bottles.rb
index 1b8ee163e1..fff38c4561 100644
--- a/Library/Homebrew/utils/bottles.rb
+++ b/Library/Homebrew/utils/bottles.rb
@@ -91,7 +91,7 @@ module Utils
       end
     end
 
-    # Collector for bottles specifications.
+    # Collector for bottle specifications.
     class Collector
       extend Forwardable
 
diff --git a/Library/Homebrew/utils/gems.rb b/Library/Homebrew/utils/gems.rb
index cdb688b5ac..866054123f 100644
--- a/Library/Homebrew/utils/gems.rb
+++ b/Library/Homebrew/utils/gems.rb
@@ -8,7 +8,7 @@
 require "English"
 
 module Homebrew
-  # Keep in sync with the Gemfile.lock's BUNDLED WITH.
+  # Keep in sync with the `Gemfile.lock`'s BUNDLED WITH.
   HOMEBREW_BUNDLER_VERSION = "1.17.3"
 
   module_function
diff --git a/Library/Homebrew/utils/pypi.rb b/Library/Homebrew/utils/pypi.rb
index d9bb621bad..6f91f31b57 100644
--- a/Library/Homebrew/utils/pypi.rb
+++ b/Library/Homebrew/utils/pypi.rb
@@ -1,7 +1,7 @@
 # typed: false
 # frozen_string_literal: true
 
-# Helper functions for updating PyPi resources.
+# Helper functions for updating PyPI resources.
 #
 # @api private
 module PyPI
@@ -38,7 +38,7 @@ module PyPI
     url
   end
 
-  # Get name, URL and SHA-256 checksum for a given PyPi package.
+  # Get name, URL and SHA-256 checksum for a given PyPI package.
   def get_pypi_info(package, version)
     metadata_url = "https://pypi.org/pypi/#{package}/#{version}/json"
     out, _, status = curl_output metadata_url, "--location"
@@ -57,7 +57,7 @@ module PyPI
     [json["info"]["name"], sdist["url"], sdist["digests"]["sha256"]]
   end
 
-  # Return true if resources were checked (even if no change)
+  # Return true if resources were checked (even if no change).
   def update_python_resources!(formula, version = nil, print_only: false, silent: false,
                                ignore_non_pypi_packages: false)
 
diff --git a/Library/Homebrew/version.rb b/Library/Homebrew/version.rb
index eda386ef35..07ef21714c 100644
--- a/Library/Homebrew/version.rb
+++ b/Library/Homebrew/version.rb
@@ -13,7 +13,7 @@ class Version
     /#{"^" if full}#{Regexp.escape(name)}(@\d[\d.]*)?#{"$" if full}/
   end
 
-  # A part of a `Version`.
+  # A part of a {Version}.
   class Token
     include Comparable
 
@@ -165,7 +165,7 @@ class Version
     end
   end
 
-  # A token representing the part of a version designating it is an alpha release.
+  # A token representing the part of a version designating it as an alpha release.
   class AlphaToken < CompositeToken
     PATTERN = /alpha[0-9]*|a[0-9]+/i.freeze
 
@@ -183,7 +183,7 @@ class Version
     end
   end
 
-  # A token representing the part of a version designating it is a beta release.
+  # A token representing the part of a version designating it as a beta release.
   class BetaToken < CompositeToken
     PATTERN = /beta[0-9]*|b[0-9]+/i.freeze
 
@@ -203,7 +203,7 @@ class Version
     end
   end
 
-  # A token representing the part of a version designating it is a pre-release.
+  # A token representing the part of a version designating it as a pre-release.
   class PreToken < CompositeToken
     PATTERN = /pre[0-9]*/i.freeze
 
@@ -223,7 +223,7 @@ class Version
     end
   end
 
-  # A token representing the part of a version designating it is a release-candidate.
+  # A token representing the part of a version designating it as a release candidate.
   class RCToken < CompositeToken
     PATTERN = /rc[0-9]*/i.freeze
 
@@ -243,7 +243,7 @@ class Version
     end
   end
 
-  # A token representing the part of a version designating it is a patch release.
+  # A token representing the part of a version designating it as a patch release.
   class PatchToken < CompositeToken
     PATTERN = /p[0-9]*/i.freeze
 
@@ -261,7 +261,7 @@ class Version
     end
   end
 
-  # A token representing the part of a version designating it is a post release.
+  # A token representing the part of a version designating it as a post release.
   class PostToken < CompositeToken
     PATTERN = /.post[0-9]+/i.freeze
 
diff --git a/Library/Homebrew/version/null.rb b/Library/Homebrew/version/null.rb
index f2b74a35e4..f08d0765af 100644
--- a/Library/Homebrew/version/null.rb
+++ b/Library/Homebrew/version/null.rb
@@ -30,7 +30,7 @@ class Version
       true
     end
 
-    # For OS::Mac::Version compatibility
+    # For {OS::Mac::Version} compatibility.
     def requires_nehalem_cpu?
       false
     end