From 20167e5f1b45c486a05d3be4c0b5209d5d1a838d Mon Sep 17 00:00:00 2001 From: EricFromCanada Date: Thu, 18 Oct 2018 21:42:43 -0400 Subject: [PATCH] Adjust comments to tidy API docs output. --- .yardopts | 3 - Library/Homebrew/cache_store.rb | 4 +- Library/Homebrew/cask/cmd/doctor.rb | 2 +- Library/Homebrew/cask/installer.rb | 6 +- Library/Homebrew/cleaner.rb | 7 +- Library/Homebrew/cmd/upgrade.rb | 4 +- Library/Homebrew/config.rb | 6 +- Library/Homebrew/cxxstdlib.rb | 6 +- Library/Homebrew/dependable.rb | 2 +- Library/Homebrew/dependency.rb | 2 +- Library/Homebrew/description_cache_store.rb | 18 +-- Library/Homebrew/dev-cmd/pull.rb | 16 +-- Library/Homebrew/diagnostic.rb | 4 +- Library/Homebrew/download_strategy.rb | 17 ++- Library/Homebrew/exceptions.rb | 28 ++--- Library/Homebrew/extend/ARGV.rb | 2 +- Library/Homebrew/extend/ENV/shared.rb | 8 +- .../Homebrew/extend/os/mac/hardware/cpu.rb | 2 +- Library/Homebrew/extend/pathname.rb | 8 +- Library/Homebrew/extend/string.rb | 2 +- Library/Homebrew/formula.rb | 110 +++++++++--------- Library/Homebrew/formula_support.rb | 4 +- Library/Homebrew/formulary.rb | 11 +- Library/Homebrew/global.rb | 2 +- Library/Homebrew/keg.rb | 3 +- Library/Homebrew/language/python.rb | 4 +- Library/Homebrew/linkage_cache_store.rb | 12 +- Library/Homebrew/messages.rb | 2 +- Library/Homebrew/migrator.rb | 4 +- Library/Homebrew/os/linux/elf.rb | 2 +- Library/Homebrew/os/mac.rb | 32 ++--- Library/Homebrew/os/mac/xquartz.rb | 14 +-- Library/Homebrew/patch.rb | 2 +- Library/Homebrew/requirement.rb | 8 +- Library/Homebrew/resource.rb | 18 +-- Library/Homebrew/rubocops/class_cop.rb | 2 +- .../Homebrew/rubocops/components_order_cop.rb | 10 +- .../rubocops/components_redundancy_cop.rb | 4 +- Library/Homebrew/rubocops/conflicts_cop.rb | 2 +- .../Homebrew/rubocops/dependency_order_cop.rb | 2 +- .../Homebrew/rubocops/extend/formula_cop.rb | 67 ++++++----- Library/Homebrew/rubocops/formula_desc_cop.rb | 4 +- Library/Homebrew/rubocops/homepage_cop.rb | 2 +- Library/Homebrew/rubocops/lines_cop.rb | 2 +- Library/Homebrew/rubocops/options_cop.rb | 2 +- Library/Homebrew/rubocops/patches_cop.rb | 2 +- Library/Homebrew/rubocops/urls_cop.rb | 2 +- Library/Homebrew/software_spec.rb | 2 +- Library/Homebrew/tap.rb | 36 +++--- Library/Homebrew/utils.rb | 6 +- Library/Homebrew/utils/inreplace.rb | 5 +- Library/Homebrew/utils/shell.rb | 2 +- 52 files changed, 267 insertions(+), 260 deletions(-) diff --git a/.yardopts b/.yardopts index 77aa469b60..74d8880383 100644 --- a/.yardopts +++ b/.yardopts @@ -7,7 +7,4 @@ --exclude Library/Homebrew/compat/ Library/Homebrew/**/*.rb - -share/doc/homebrew/*.html -Library/Homebrew/*.md -share/doc/homebrew/*.md *.md diff --git a/Library/Homebrew/cache_store.rb b/Library/Homebrew/cache_store.rb index cccad7d01c..aaaeb8604c 100644 --- a/Library/Homebrew/cache_store.rb +++ b/Library/Homebrew/cache_store.rb @@ -2,7 +2,7 @@ require "json" # # `CacheStoreDatabase` acts as an interface to a persistent storage mechanism -# residing in the `HOMEBREW_CACHE` +# residing in the `HOMEBREW_CACHE`. # class CacheStoreDatabase # Yields the cache store database. @@ -107,7 +107,7 @@ end # # `CacheStore` provides methods to mutate and fetch data from a persistent -# storage mechanism +# storage mechanism. # class CacheStore # @param [CacheStoreDatabase] database diff --git a/Library/Homebrew/cask/cmd/doctor.rb b/Library/Homebrew/cask/cmd/doctor.rb index b14c656f47..353ce7b8fc 100644 --- a/Library/Homebrew/cask/cmd/doctor.rb +++ b/Library/Homebrew/cask/cmd/doctor.rb @@ -42,7 +42,7 @@ module Cask end # This could be done by calling into Homebrew, but the situation - # where "doctor" is needed is precisely the situation where such + # where `brew doctor` is needed is precisely the situation where such # things are less dependable. def check_install_location ohai "Homebrew Cask Install Location" diff --git a/Library/Homebrew/cask/installer.rb b/Library/Homebrew/cask/installer.rb index fde3cc7c7f..255283cd76 100644 --- a/Library/Homebrew/cask/installer.rb +++ b/Library/Homebrew/cask/installer.rb @@ -221,9 +221,9 @@ module Cask end end - # TODO: move dependencies to a separate class - # dependencies should also apply for "brew cask stage" - # override dependencies with --force or perhaps --force-deps + # TODO: move dependencies to a separate class, + # dependencies should also apply for `brew cask stage`, + # override dependencies with `--force` or perhaps `--force-deps` def satisfy_dependencies return unless @cask.depends_on diff --git a/Library/Homebrew/cleaner.rb b/Library/Homebrew/cleaner.rb index 7456e18d65..9eed49ac61 100644 --- a/Library/Homebrew/cleaner.rb +++ b/Library/Homebrew/cleaner.rb @@ -1,8 +1,9 @@ # Cleans a newly installed keg. # By default: -# * removes .la files -# * removes perllocal.pod files -# * removes .packlist files +# +# * removes `.la` files +# * removes `perllocal.pod` files +# * removes `.packlist` files # * removes empty directories # * sets permissions on executables # * removes unresolved symlinks diff --git a/Library/Homebrew/cmd/upgrade.rb b/Library/Homebrew/cmd/upgrade.rb index 3fbd3ed6fd..7b4b8c5c96 100644 --- a/Library/Homebrew/cmd/upgrade.rb +++ b/Library/Homebrew/cmd/upgrade.rb @@ -91,8 +91,8 @@ module Homebrew def upgrade_formulae(formulae_to_install) return if formulae_to_install.empty? - # Sort keg_only before non-keg_only formulae to avoid any needless conflicts - # with outdated, non-keg_only versions of formulae being upgraded. + # Sort keg-only before non-keg-only formulae to avoid any needless conflicts + # with outdated, non-keg-only versions of formulae being upgraded. formulae_to_install.sort! do |a, b| if !a.keg_only? && b.keg_only? 1 diff --git a/Library/Homebrew/config.rb b/Library/Homebrew/config.rb index 73b0081cc8..444db9ac35 100644 --- a/Library/Homebrew/config.rb +++ b/Library/Homebrew/config.rb @@ -2,13 +2,13 @@ unless ENV["HOMEBREW_BREW_FILE"] raise "HOMEBREW_BREW_FILE was not exported! Please call bin/brew directly!" end -# Path to `bin/brew` main executable in HOMEBREW_PREFIX +# Path to `bin/brew` main executable in `HOMEBREW_PREFIX` HOMEBREW_BREW_FILE = Pathname.new(ENV["HOMEBREW_BREW_FILE"]) # Where we link under HOMEBREW_PREFIX = Pathname.new(ENV["HOMEBREW_PREFIX"]) -# Where .git is found +# Where `.git` is found HOMEBREW_REPOSITORY = Pathname.new(ENV["HOMEBREW_REPOSITORY"]) # Where we store most of Homebrew, taps, and various metadata @@ -38,7 +38,7 @@ HOMEBREW_CACHE_FORMULA = HOMEBREW_CACHE/"Formula" # Where build, postinstall, and test logs of formulae are written to HOMEBREW_LOGS = Pathname.new(ENV["HOMEBREW_LOGS"] || "~/Library/Logs/Homebrew/").expand_path -# Must use /tmp instead of $TMPDIR because long paths break Unix domain sockets +# Must use `/tmp` instead of `TMPDIR` because long paths break Unix domain sockets HOMEBREW_TEMP = begin # /tmp fallback is here for people auto-updating from a version where # HOMEBREW_TEMP isn't set. diff --git a/Library/Homebrew/cxxstdlib.rb b/Library/Homebrew/cxxstdlib.rb index 166b86209f..b89c8b8a2c 100644 --- a/Library/Homebrew/cxxstdlib.rb +++ b/Library/Homebrew/cxxstdlib.rb @@ -40,10 +40,10 @@ class CxxStdlib @compiler = compiler.to_sym end - # If either package doesn't use C++, all is well - # libstdc++ and libc++ aren't ever intercompatible + # 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, or 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 ce3b8f426d..ce0f5fd4e0 100644 --- a/Library/Homebrew/dependable.rb +++ b/Library/Homebrew/dependable.rb @@ -1,7 +1,7 @@ require "options" module Dependable - # :run and :linked are no longer used but keep them here to avoid them being + # `:run` and `:linked` are no longer used but keep them here to avoid them being # misused in future. RESERVED_TAGS = [:build, :optional, :recommended, :run, :test, :linked].freeze diff --git a/Library/Homebrew/dependency.rb b/Library/Homebrew/dependency.rb index 126df977e1..04979e1c08 100644 --- a/Library/Homebrew/dependency.rb +++ b/Library/Homebrew/dependency.rb @@ -71,7 +71,7 @@ class Dependency class << self # Expand the dependencies of dependent recursively, optionally yielding - # [dependent, dep] pairs to allow callers to apply arbitrary filters to + # `[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 # optionals and recommendeds based on what the dependent has asked for. diff --git a/Library/Homebrew/description_cache_store.rb b/Library/Homebrew/description_cache_store.rb index a7094c569c..984cefd165 100644 --- a/Library/Homebrew/description_cache_store.rb +++ b/Library/Homebrew/description_cache_store.rb @@ -4,24 +4,24 @@ require "searchable" # # `DescriptionCacheStore` provides methods to fetch and mutate linkage-specific data used -# by the `brew linkage` command +# by the `brew linkage` command. # class DescriptionCacheStore < CacheStore include Searchable # Inserts a formula description into the cache if it does not exist or - # updates the formula description if it does exist + # updates the formula description if it does exist. # - # @param [String] formula_name: the name of the formula to set - # @param [String] description: the description from the formula to set + # @param formula_name [String] the name of the formula to set + # @param description [String] the description from the formula to set # @return [nil] def update!(formula_name, description) database.set(formula_name, description) end - # Delete the formula description from the `DescriptionCacheStore` + # Delete the formula description from the `DescriptionCacheStore`. # - # @param [String] formula_name: the name of the formula to delete + # @param formula_name [String] the name of the formula to delete # @return [nil] def delete!(formula_name) database.delete(formula_name) @@ -37,7 +37,7 @@ class DescriptionCacheStore < CacheStore # Use an update report to update the `DescriptionCacheStore`. # - # @param [Report] report: an update report generated by cmd/update.rb + # @param report [Report] an update report generated by cmd/update.rb # @return [nil] def update_from_report!(report) return populate_if_empty! if database.empty? @@ -55,7 +55,7 @@ class DescriptionCacheStore < CacheStore # Use an array of formulae names to update the `DescriptionCacheStore`. # - # @param [Array] formula_names: the formulae to update. + # @param formula_names [Array] the formulae to update # @return [nil] def update_from_formula_names!(formula_names) return populate_if_empty! if database.empty? @@ -71,7 +71,7 @@ class DescriptionCacheStore < CacheStore # Use an array of formulae names to delete them from the `DescriptionCacheStore`. # - # @param [Array] formula_names: the formulae to delete. + # @param formula_names [Array] the formulae to delete # @return [nil] def delete_from_formula_names!(formula_names) return if database.empty? diff --git a/Library/Homebrew/dev-cmd/pull.rb b/Library/Homebrew/dev-cmd/pull.rb index bc133a3334..1779be9478 100644 --- a/Library/Homebrew/dev-cmd/pull.rb +++ b/Library/Homebrew/dev-cmd/pull.rb @@ -453,9 +453,9 @@ module Homebrew { files: files, formulae: formulae, others: others } end - # Get current formula versions without loading formula definition in this process - # Returns info as a hash (type => version), for pull.rb's internal use - # Uses special key :nonexistent => true for nonexistent formulae + # Get current formula versions without loading formula definition in this process. + # Returns info as a hash (type => version), for pull.rb's internal use. + # Uses special key `:nonexistent => true` for nonexistent formulae. def current_versions_from_info_external(formula_name) info = FormulaInfoFromJson.lookup(formula_name) versions = {} @@ -540,7 +540,7 @@ module Homebrew false end - # Formula info drawn from an external "brew info --json" call + # Formula info drawn from an external `brew info --json` call class FormulaInfoFromJson # The whole info structure parsed from the JSON attr_accessor :info @@ -549,8 +549,8 @@ module Homebrew @info = info end - # Looks up formula on disk and reads its info - # Returns nil if formula is absent or if there was an error reading it + # Looks up formula on disk and reads its info. + # Returns nil if formula is absent or if there was an error reading it. def self.lookup(name) json = Utils.popen_read(HOMEBREW_BREW_FILE, "info", "--json=v1", name) @@ -600,11 +600,11 @@ module Homebrew end end - # Bottle info as used internally by pull, with alternate platform support + # Bottle info as used internally by pull, with alternate platform support. class BottleInfo # URL of bottle as string attr_accessor :url - # Expected SHA256 as string + # Expected SHA-256 as string attr_accessor :sha256 def initialize(url, sha256) diff --git a/Library/Homebrew/diagnostic.rb b/Library/Homebrew/diagnostic.rb index eca5c3cad0..7f84168060 100644 --- a/Library/Homebrew/diagnostic.rb +++ b/Library/Homebrew/diagnostic.rb @@ -59,8 +59,8 @@ module Homebrew class Checks ############# HELPERS - # Finds files in HOMEBREW_PREFIX *and* /usr/local. - # Specify paths relative to a prefix eg. "include/foo.h". + # Finds files in `HOMEBREW_PREFIX` *and* /usr/local. + # Specify paths relative to a prefix e.g. "include/foo.h". # Sets @found for your convenience. def find_relative_paths(*relative_paths) @found = [HOMEBREW_PREFIX, "/usr/local"].uniq.reduce([]) do |found, prefix| diff --git a/Library/Homebrew/download_strategy.rb b/Library/Homebrew/download_strategy.rb index 2c8cff34c5..fb803c899e 100644 --- a/Library/Homebrew/download_strategy.rb +++ b/Library/Homebrew/download_strategy.rb @@ -72,8 +72,8 @@ class AbstractDownloadStrategy end private :chdir - # @!attribute [r] - # return most recent modified time for all files in the current working directory after stage. + # @!attribute [r] source_modified_time + # Returns the most recent modified time for all files in the current working directory after stage. def source_modified_time Pathname.pwd.to_enum(:find).select(&:file?).map(&:mtime).max end @@ -405,7 +405,7 @@ class CurlDownloadStrategy < AbstractFileDownloadStrategy end end -# Detect and download from Apache Mirror +# Detect and download from Apache Mirror. class CurlApacheMirrorDownloadStrategy < CurlDownloadStrategy def mirrors return @combined_mirrors if defined?(@combined_mirrors) @@ -440,7 +440,7 @@ class CurlApacheMirrorDownloadStrategy < CurlDownloadStrategy end # Download via an HTTP POST. -# Query parameters on the URL are converted into POST parameters +# Query parameters on the URL are converted into POST parameters. class CurlPostDownloadStrategy < CurlDownloadStrategy private @@ -477,7 +477,7 @@ end # S3DownloadStrategy downloads tarballs from AWS S3. # To use it, add `:using => :s3` to the URL section of your # formula. This download strategy uses AWS access tokens (in the -# environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) +# environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`) # to sign the request. This strategy is good in a corporate setting, # because it lets you use a private S3 bucket as a repo for internal # distribution. (It will work for public buckets as well.) @@ -510,7 +510,7 @@ end # Private Repository. To use it, add # `:using => :github_private_repo` to the URL section of # your formula. This download strategy uses GitHub access tokens (in the -# environment variables HOMEBREW_GITHUB_API_TOKEN) to sign the request. This +# environment variables `HOMEBREW_GITHUB_API_TOKEN`) to sign the request. This # strategy is suitable for corporate use just like S3DownloadStrategy, because # it lets you use a private GitHub repository for internal distribution. It # works with public one, but in that case simply use CurlDownloadStrategy. @@ -568,7 +568,7 @@ end # GitHubPrivateRepositoryReleaseDownloadStrategy downloads tarballs from GitHub # Release assets. To use it, add `:using => :github_private_release` to the URL section # of your formula. This download strategy uses GitHub access tokens (in the -# environment variables HOMEBREW_GITHUB_API_TOKEN) to sign the request. +# environment variables `HOMEBREW_GITHUB_API_TOKEN`) to sign the request. class GitHubPrivateRepositoryReleaseDownloadStrategy < GitHubPrivateRepositoryDownloadStrategy def parse_url_pattern url_pattern = %r{https://github.com/([^/]+)/([^/]+)/releases/download/([^/]+)/(\S+)} @@ -615,8 +615,7 @@ end # authentication. If a public/private keypair is configured, it will not # prompt for a password. # -# Usage: -# +# @example # class Abc < Formula # url "scp://example.com/src/abc.1.0.tar.gz" # ... diff --git a/Library/Homebrew/exceptions.rb b/Library/Homebrew/exceptions.rb index 6ad85aeb09..ce13a1a24d 100644 --- a/Library/Homebrew/exceptions.rb +++ b/Library/Homebrew/exceptions.rb @@ -436,9 +436,9 @@ class BuildError < RuntimeError end end -# raised by FormulaInstaller.check_dependencies_bottled and -# FormulaInstaller.install if the formula or its dependencies are not bottled -# and are being installed on a system without necessary build tools +# Raised by {FormulaInstaller#check_dependencies_bottled} and +# {FormulaInstaller#install} if the formula or its dependencies are not bottled +# and are being installed on a system without necessary build tools. class BuildToolsError < RuntimeError def initialize(formulae) super <<~EOS @@ -450,9 +450,9 @@ class BuildToolsError < RuntimeError end end -# raised by Homebrew.install, Homebrew.reinstall, and Homebrew.upgrade +# Raised by Homebrew.install, Homebrew.reinstall, and Homebrew.upgrade # if the user passes any flags/environment that would case a bottle-only -# installation on a system without build tools to fail +# installation on a system without build tools to fail. class BuildFlagsError < RuntimeError def initialize(flags, bottled: true) if flags.length > 1 @@ -478,8 +478,8 @@ class BuildFlagsError < RuntimeError end end -# raised by CompilerSelector if the formula fails with all of -# the compilers available on the user's system +# Raised by {CompilerSelector} if the formula fails with all of +# the compilers available on the user's system. class CompilerSelectionError < RuntimeError def initialize(formula) super <<~EOS @@ -489,7 +489,7 @@ class CompilerSelectionError < RuntimeError end end -# Raised in Resource.fetch +# Raised in {Resource#fetch}. class DownloadError < RuntimeError def initialize(resource, cause) super <<~EOS @@ -500,7 +500,7 @@ class DownloadError < RuntimeError end end -# raised in CurlDownloadStrategy.fetch +# Raised in {CurlDownloadStrategy#fetch}. class CurlDownloadStrategyError < RuntimeError def initialize(url) case url @@ -512,14 +512,14 @@ class CurlDownloadStrategyError < RuntimeError end end -# raised in ScpDownloadStrategy.fetch +# Raised in {ScpDownloadStrategy#fetch}. class ScpDownloadStrategyError < RuntimeError def initialize(cause) super "Download failed: #{cause}" end end -# raised by safe_system in utils.rb +# Raised by {#safe_system} in `utils.rb`. class ErrorDuringExecution < RuntimeError attr_reader :cmd attr_reader :status @@ -556,10 +556,10 @@ class ErrorDuringExecution < RuntimeError end end -# raised by Pathname#verify_checksum when "expected" is nil or empty +# Raised by {Pathname#verify_checksum} when "expected" is nil or empty. class ChecksumMissingError < ArgumentError; end -# raised by Pathname#verify_checksum when verification fails +# Raised by {Pathname#verify_checksum} when verification fails. class ChecksumMismatchError < RuntimeError attr_reader :expected, :hash_type @@ -589,7 +589,7 @@ class DuplicateResourceError < ArgumentError end end -# raised when a single patch file is not found and apply hasn't been specified +# Raised when a single patch file is not found and apply hasn't been specified. class MissingApplyError < RuntimeError; end class BottleFormulaUnavailableError < RuntimeError diff --git a/Library/Homebrew/extend/ARGV.rb b/Library/Homebrew/extend/ARGV.rb index a5d8a32802..efa6b6a2c8 100644 --- a/Library/Homebrew/extend/ARGV.rb +++ b/Library/Homebrew/extend/ARGV.rb @@ -243,7 +243,7 @@ module HomebrewArgvExtension include? "--fetch-HEAD" end - # eg. `foo -ns -i --bar` has three switches, n, s and i + # e.g. `foo -ns -i --bar` has three switches: `n`, `s` and `i` def switch?(char) return false if char.length > 1 diff --git a/Library/Homebrew/extend/ENV/shared.rb b/Library/Homebrew/extend/ENV/shared.rb index 4a9e90ca21..2089283cfc 100644 --- a/Library/Homebrew/extend/ENV/shared.rb +++ b/Library/Homebrew/extend/ENV/shared.rb @@ -88,11 +88,11 @@ module SharedEnvExtension # Prepends a directory to `PATH`. # Is the formula struggling to find the pkgconfig file? Point it to it. - # This is done automatically for `keg_only` formulae. + # 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. 
ENV.prepend_path "PATH", which("emacs").dirname
) + # don't accidentally override superenv shims or formulae's `bin` directories, e.g. + # 
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 @@ -194,7 +194,7 @@ module SharedEnvExtension end # Snow Leopard defines an NCURSES value the opposite of most distros. - # See: https://bugs.python.org/issue6848 + # @see https://bugs.python.org/issue6848 # Currently only used by aalib in core. def ncurses_define append "CPPFLAGS", "-DNCURSES_OPAQUE=0" diff --git a/Library/Homebrew/extend/os/mac/hardware/cpu.rb b/Library/Homebrew/extend/os/mac/hardware/cpu.rb index 340e421221..a3c3df8f03 100644 --- a/Library/Homebrew/extend/os/mac/hardware/cpu.rb +++ b/Library/Homebrew/extend/os/mac/hardware/cpu.rb @@ -94,7 +94,7 @@ module Hardware # Determines whether the current CPU and macOS combination # can run an executable of the specified architecture. # `arch` is a symbol in the same format returned by - # Hardware::CPU.family + # {Hardware::CPU.family}. def can_run?(arch) if Hardware::CPU.intel? intel_can_run? arch diff --git a/Library/Homebrew/extend/pathname.rb b/Library/Homebrew/extend/pathname.rb index 02ff1e35b4..1f67eab52b 100644 --- a/Library/Homebrew/extend/pathname.rb +++ b/Library/Homebrew/extend/pathname.rb @@ -145,7 +145,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? @@ -196,7 +196,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) @@ -212,7 +212,7 @@ class Pathname File.extname(basename) end - # for filetypes we support, basename without extension + # For filetypes we support, basename without extension def stem File.basename((path = to_s), extname(path)) end @@ -351,7 +351,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) mkpath java_home = if java_version diff --git a/Library/Homebrew/extend/string.rb b/Library/Homebrew/extend/string.rb index 64be4d5620..0b2fa3e379 100644 --- a/Library/Homebrew/extend/string.rb +++ b/Library/Homebrew/extend/string.rb @@ -18,7 +18,7 @@ class NilClass def chuzzle; end end -# used by the inreplace function (in utils.rb) +# Used by the inreplace function (in `utils.rb`). module StringInreplaceExtension attr_accessor :errors diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index 290187466d..83d7c7e876 100644 --- a/Library/Homebrew/formula.rb +++ b/Library/Homebrew/formula.rb @@ -29,8 +29,8 @@ require "mktemp" # Make sure you check with `brew search` that the name is free! # @abstract # @see SharedEnvExtension -# @see FileUtils # @see Pathname +# @see https://www.rubydoc.info/stdlib/fileutils FileUtils # @see https://docs.brew.sh/Formula-Cookbook Formula Cookbook # @see https://github.com/styleguide/ruby Ruby Style Guide # @@ -57,8 +57,9 @@ class Formula # 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 - # HOMEBREW_PREFIX is available in the embedded patch. - # inreplace supports regular expressions. + # `HOMEBREW_PREFIX` is available in the embedded patch. + # + # `inreplace` supports regular expressions: # 
inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"
# @see Utils::Inreplace.inreplace @@ -132,7 +133,7 @@ class Formula # Used for creating new Homebrew versions of software without new upstream # versions. - # @see .revision + # @see .revision= attr_reader :revision # Used to change version schemes for packages @@ -143,7 +144,7 @@ class Formula attr_reader :buildpath # The current working directory during tests. - # Will only be non-`nil` inside {#test}. + # Will only be non-`nil` inside {.test}. attr_reader :testpath # When installing a bottle (binary package) from a local path this will be @@ -157,13 +158,13 @@ class Formula attr_reader :active_log_type # The {BuildOptions} for this {Formula}. Lists the arguments passed and any - # {#options} in the {Formula}. Note that these may differ at different times + # {.option}s in the {Formula}. Note that these may differ at different times # during the installation of a {Formula}. This is annoying but the result of # state that we're trying to eliminate. # @return [BuildOptions] attr_accessor :build - # A {Boolean} indicating whether this formula should be considered outdated + # A Boolean indicating 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] @@ -265,7 +266,7 @@ class Formula public # The alias path that was used to install this formula, if it exists. - # Can differ from alias_path, which is the alias used to find the formula, + # Can differ from {#alias_path}, which is the alias used to find the formula, # and is specified to this instance. def installed_alias_path path = build.source["path"] if build.is_a?(Tab) @@ -344,12 +345,12 @@ class Formula # The description of the software. # @method desc - # @see .desc + # @see .desc= delegate desc: :"self.class" # The homepage for the software. # @method homepage - # @see .homepage + # @see .homepage= delegate homepage: :"self.class" # The version for the currently active {SoftwareSpec}. @@ -413,7 +414,7 @@ class Formula end end - # All of 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| @@ -555,12 +556,12 @@ class Formula linked_keg.symlink? end - # Is the formula linked to opt? + # Is the formula linked to `opt`? def optlinked? opt_prefix.symlink? end - # Is formula's linked keg points to the prefix. + # If a formula's linked keg points to the prefix. def prefix_linked?(v = pkg_version) return false unless linked? @@ -597,7 +598,7 @@ class Formula # This is symlinked into `HOMEBREW_PREFIX` after installation or with # `brew link` for formulae that are not keg-only. # - # Need to install into the {.bin} but the makefile doesn't mkdir -p prefix/bin? + # Need to install into the {.bin} but the makefile doesn't `mkdir -p prefix/bin`? # 
bin.mkpath
# # No `make install` available? @@ -643,7 +644,7 @@ class Formula # The directory where the formula's binaries should be installed. # This is not symlinked into `HOMEBREW_PREFIX`. # It is also commonly used to install files that we do not wish to be - # symlinked into HOMEBREW_PREFIX from one of the other directories and + # symlinked into `HOMEBREW_PREFIX` from one of the other directories and # instead manually create symlinks or wrapper scripts into e.g. {#bin}. def libexec prefix/"libexec" @@ -652,7 +653,7 @@ class Formula # The root directory where the formula's manual pages should be installed. # 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 + # Often one of the more specific `man` functions should be used instead, # e.g. {#man1} def man share/"man" @@ -786,14 +787,14 @@ class Formula # The directory where the formula's configuration files should be installed. # Anything using `etc.install` will not overwrite other files on e.g. upgrades # but will write a new file named `*.default`. - # This directory is not inside the `HOMEBREW_CELLAR` so it is persisted + # This directory is not inside the `HOMEBREW_CELLAR` so it persists # across upgrades. def etc (HOMEBREW_PREFIX/"etc").extend(InstallRenamed) end # The directory where the formula's variable files should be installed. - # This directory is not inside the `HOMEBREW_CELLAR` so it is persisted + # This directory is not inside the `HOMEBREW_CELLAR` so it persists # across upgrades. def var HOMEBREW_PREFIX/"var" @@ -872,8 +873,7 @@ class Formula end # This method can be overridden to provide a plist. - # For more examples read Apple's handy manpage: - # https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/plist.5.html + # @see https://www.unix.com/man-page/all/5/plist/ Apple's plist(5) man page # 
def plist; <<~EOS
   #  
   #  
@@ -894,6 +894,7 @@ class Formula
   #    /dev/null
   #    StandardOutPath
   #    /dev/null
+  #  
   #  
   #  EOS
   # end
@@ -925,7 +926,7 @@ class Formula # but no version number. Only the active version will be linked here if # multiple versions are installed. # - # This is the prefered way to refer a formula in plists or from another + # This is the preferred way to refer to a formula in plists or from another # formula, as the path is stable even when the software is updated. # 
args << "--with-readline=#{Formula["readline"].opt_prefix}" if build.with? "readline"
def opt_prefix @@ -1029,7 +1030,7 @@ class Formula # # 
def caveats
   #   s = <<~EOS
-  #     Print some important notice to the user when `brew info ` is
+  #     Print some important notice to the user when `brew info [formula]` is
   #     called or when brewing a formula.
   #     This is optional. You can use all the vars like #{version} here.
   #   EOS
@@ -1040,8 +1041,8 @@ class Formula
     nil
   end
 
-  # rarely, you don't want your library symlinked into the main prefix
-  # see gettext.rb for an example
+  # Rarely, you don't want your library symlinked into the main prefix.
+  # See `gettext.rb` for an example.
   def keg_only?
     return false unless keg_only_reason
 
@@ -1319,7 +1320,7 @@ class Formula
   end
 
   # Standard parameters for CMake builds.
-  # Setting CMAKE_FIND_FRAMEWORK to "LAST" tells CMake to search for our
+  # 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
@@ -1951,7 +1952,7 @@ class Formula
   end
 
   # Create a temporary directory then yield. When the block returns,
-  # recursively delete the temporary directory. Passing opts[:retain]
+  # recursively delete the temporary directory. Passing `opts[:retain]`
   # or calling `do |staging| ... staging.retain!` in the block will skip
   # the deletion and retain the temporary directory's contents.
   def mktemp(prefix = name, opts = {})
@@ -2159,10 +2160,10 @@ class Formula
     attr_rw :revision
 
     # @!attribute [w] version_scheme
-    # Used for creating new Homebrew versions schemes. For example, if we want
+    # 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.
-    # E.g. to move from 20151020 scheme to 1.0.0 we need to increment
+    # 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.
     # `0` if unset.
@@ -2177,14 +2178,15 @@ class Formula
     end
 
     # @!attribute [w] url
-    # The URL used to download the source for the {#stable} version of the formula.
+    # The URL used to download the source for the {.stable} version of the formula.
     # We prefer `https` for security and proxy reasons.
     # If not inferrable, specify the download strategy with `:using => ...`
-    #     `:git`, `:hg`, `:svn`, `:bzr`, `:cvs`,
-    #     `:curl` (normal file download. Will also extract.)
-    #     `:nounzip` (without extracting)
-    #     `:post` (download via an HTTP POST)
-    #     `:s3` (download from S3 using signed request)
+    #
+    # - `:git`, `:hg`, `:svn`, `:bzr`, `:fossil`, `:cvs`,
+    # - `:curl` (normal file download. Will also extract.)
+    # - `:nounzip` (without extracting)
+    # - `:post` (download via an HTTP POST)
+    # - `:s3` (download from S3 using signed request)
     #
     # 
url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"

     # 
url "https://some.dont.provide.archives.example.com",
@@ -2196,7 +2198,7 @@ class Formula
     end
 
     # @!attribute [w] version
-    # The version string for the {#stable} version of the formula.
+    # The version string for the {.stable} version of the formula.
     # The version is autodetected from the URL and/or tag so only needs to be
     # declared if it cannot be autodetected correctly.
     #
@@ -2206,7 +2208,7 @@ class Formula
     end
 
     # @!attribute [w] mirror
-    # Additional URLs for the {#stable} version of the formula.
+    # Additional URLs for the {.stable} version of the formula.
     # These are only used if the {.url} fails to download. It's optional and
     # there can be more than one. Generally we add them when the main {.url}
     # is unreliable. If {.url} is really unreliable then we may swap the
@@ -2220,8 +2222,8 @@ class Formula
 
     # @!attribute [w] sha256
     # @scope class
-    # To verify the {#cached_download}'s integrity and security we verify the
-    # SHA-256 hash matches what we've declared in the {Formula}. To quickly fill
+    # 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
     # this value you can leave it blank and run `brew fetch --force` and it'll
     # tell you the currently valid value.
     #
@@ -2237,7 +2239,7 @@ class Formula
     # and you haven't passed or previously used any options on this formula.
     #
     # If you maintain your own repository, you can add your own bottle links.
-    # https://docs.brew.sh/Bottles
+    # @see https://docs.brew.sh/Bottles
     # You can ignore this block entirely if submitting to Homebrew/homebrew-core.
     # It'll be handled for you by the Brew Test Bot.
     #
@@ -2251,11 +2253,11 @@ class Formula
     #   sha256 "1121cfccd5913f0a63fec40a6ffd44ea64f9dc135c66634ba001d10bcf4302a2" => :mavericks
     # end

     #
-    # Only formulae where the upstream URL breaks or moves frequently, require compile
+    # Only formulae where the upstream URL breaks or moves frequently, require compiling
     # or have a reasonable amount of patches/resources should be bottled.
     # Formulae which do not meet the above requirements should not be bottled.
     #
-    # Formulae which should not be bottled & can be installed without any compile
+    # Formulae which should not be bottled and can be installed without any compile
     # required should be tagged with:
     # 
bottle :unneeded

     #
@@ -2272,7 +2274,7 @@ class Formula
     end
 
     # @!attribute [w] stable
-    # Allows adding {.depends_on} and {#patch}es just to the {.stable} {SoftwareSpec}.
+    # 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.
     #
@@ -2314,7 +2316,7 @@ class Formula
     # This can be installed by passing the `--HEAD` option to allow
     # installing software directly from a branch of a version-control repository.
     # If called as a method this provides just the {url} for the {SoftwareSpec}.
-    # If a block is provided you can also add {.depends_on} and {#patch}es just to the {.head} {SoftwareSpec}.
+    # If a block is provided you can also add {.depends_on} and {Patch}es just to the {.head} {SoftwareSpec}.
     # The download strategies (e.g. `:using =>`) are the same as for {url}.
     # `master` is the default branch and doesn't need stating with a `:branch` parameter.
     # 
head "https://we.prefer.https.over.git.example.com/.git"

@@ -2333,8 +2335,8 @@ class Formula
     end
 
     # Additional downloads can be defined as resources and accessed in the
-    # install method. Resources can also be defined inside a stable, devel, or
-    # head block. This mechanism replaces ad-hoc "subformula" classes.
+    # install method. Resources can also be defined inside a {.stable}, {.devel} or
+    # {.head} block. This mechanism replaces ad-hoc "subformula" classes.
     # 
resource "additional_files" do
     #   url "https://example.com/additional-stuff.tar.gz"
     #   sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
@@ -2378,11 +2380,10 @@ class Formula
     # depends_on :ld64 # Sometimes ld fails on `MacOS.version < :leopard`. Then use this.
     # depends_on :x11 => :optional # X11/XQuartz components.
     # depends_on :osxfuse # Permits the use of the upstream signed binary or our source package.
-    # depends_on :tuntap # Does the same thing as above. This is vital for Yosemite and above.
+    # depends_on :tuntap # Does the same thing as above. This is vital for Yosemite and above.

     # 
# It is possible to only depend on something if
     # # `build.with?` or `build.without? "another_formula"`:
-    # depends_on "postgresql" if build.without? "sqlite"
-    #
+    # depends_on "postgresql" if build.without? "sqlite"

     # 
# Python 3.x if the `--with-python` is given to `brew install example`
     # depends_on "python3" => :optional

     # 
# Python 2.7:
@@ -2397,10 +2398,11 @@ class Formula
     # 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"`
-    # Note, that for {.depends_on} that are `:optional` or `:recommended`, options
+    # Note that for {.depends_on} that are `:optional` or `:recommended`, options
     # are generated automatically.
     #
     # There are also some special options:
+    #
     # - `: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"

@@ -2491,10 +2493,10 @@ class Formula
       @skip_clean_paths ||= Set.new
     end
 
-    # Software that will not be sym-linked into the `brew --prefix` will only
+    # Software that will not be symlinked into the `brew --prefix` will only
     # live in its Cellar. Other formulae can depend on it and then brew will
     # add the necessary includes and libs (etc.) during the brewing of that
-    # other formula. But generally, keg_only formulae are not in your PATH
+    # other formula. But generally, keg-only formulae are not in your PATH
     # and not seen by compilers if you build your own software outside of
     # Homebrew. This way, we don't shadow software provided by macOS.
     # 
keg_only :provided_by_macos

@@ -2503,7 +2505,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
@@ -2538,13 +2540,13 @@ class Formula
       specs.each { |spec| spec.needs(*standards) }
     end
 
-    # Test (is required for new formula and makes us happy).
+    # A test is required for new formulae and makes us happy.
     # @return [Boolean]
     #
     # The block will create, run in and delete a temporary directory.
     #
     # We are fine if the executable does not error out, so we know linking
-    # and building the software was ok.
+    # and building the software was OK.
     # 
system bin/"foobar", "--version"

     #
     # 
(testpath/"test.file").write <<~EOS
diff --git a/Library/Homebrew/formula_support.rb b/Library/Homebrew/formula_support.rb
index fcdd45630f..05347a10d1 100644
--- a/Library/Homebrew/formula_support.rb
+++ b/Library/Homebrew/formula_support.rb
@@ -1,4 +1,4 @@
-# Used to track formulae that cannot be installed at the same time
+# 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
@@ -39,7 +39,7 @@ class KegOnlyReason
   end
 end
 
-# Used to annotate formulae that don't require compiling or cannot build bottle.
+# Used to annotate formulae that don't require compiling or cannot build a bottle.
 class BottleDisableReason
   SUPPORTED_TYPES = [:unneeded, :disable].freeze
 
diff --git a/Library/Homebrew/formulary.rb b/Library/Homebrew/formulary.rb
index 044f8e242e..44f40685fa 100644
--- a/Library/Homebrew/formulary.rb
+++ b/Library/Homebrew/formulary.rb
@@ -1,7 +1,7 @@
 require "digest/md5"
 require "extend/cachable"
 
-# 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.
 
 module Formulary
@@ -175,7 +175,7 @@ module Formulary
     end
   end
 
-  # Loads formulae from disk using a path
+  # Loads formulae from disk using a path.
   class FromPathLoader < FormulaLoader
     def initialize(path)
       path = Pathname.new(path).expand_path
@@ -183,7 +183,7 @@ module Formulary
     end
   end
 
-  # Loads formulae from URLs
+  # Loads formulae from URLs.
   class FromUrlLoader < FormulaLoader
     attr_reader :url
 
@@ -280,7 +280,7 @@ module Formulary
     end
   end
 
-  # Load formulae directly from their contents
+  # Load formulae directly from their contents.
   class FormulaContentsLoader < FormulaLoader
     # The formula's contents
     attr_reader :contents
@@ -298,7 +298,8 @@ module Formulary
   end
 
   # Return a Formula instance for the given reference.
-  # `ref` is string containing:
+  # `ref` is a string containing:
+  #
   # * a formula name
   # * a formula pathname
   # * a formula URL
diff --git a/Library/Homebrew/global.rb b/Library/Homebrew/global.rb
index 0057791b19..9d09992835 100644
--- a/Library/Homebrew/global.rb
+++ b/Library/Homebrew/global.rb
@@ -51,7 +51,7 @@ HOMEBREW_USER_AGENT_FAKE_SAFARI =
   "(KHTML, like Gecko) Version/10.0.3 Safari/602.4.8".freeze
 
 # Bintray fallback is here for people auto-updating from a version where
-# HOMEBREW_BOTTLE_DEFAULT_DOMAIN isn't set.
+# `HOMEBREW_BOTTLE_DEFAULT_DOMAIN` isn't set.
 HOMEBREW_BOTTLE_DEFAULT_DOMAIN = if ENV["HOMEBREW_BOTTLE_DEFAULT_DOMAIN"]
   ENV["HOMEBREW_BOTTLE_DEFAULT_DOMAIN"]
 elsif OS.mac?
diff --git a/Library/Homebrew/keg.rb b/Library/Homebrew/keg.rb
index 1ed943c58c..032f3e2e1e 100644
--- a/Library/Homebrew/keg.rb
+++ b/Library/Homebrew/keg.rb
@@ -111,9 +111,8 @@ class Keg
   ].freeze
 
   # Given an array of kegs, this method will try to find some other kegs
-  # that depend on them.
+  # that depend on them. If it does, it returns:
   #
-  # If it does, it returns:
   # - some kegs in the passed array that have installed dependents
   # - some installed dependents of those kegs.
   #
diff --git a/Library/Homebrew/language/python.rb b/Library/Homebrew/language/python.rb
index 66d6bcabd4..b79ed19505 100644
--- a/Library/Homebrew/language/python.rb
+++ b/Library/Homebrew/language/python.rb
@@ -94,7 +94,7 @@ module Language
       end
 
       # Instantiates, creates, and yields a {Virtualenv} object for use from
-      # Formula#install, which provides helper methods for instantiating and
+      # {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"`)
@@ -140,7 +140,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 python2, or to resolve an ambiguous
       # case where it's not clear whether python or python2 should be the
       # default guess.
diff --git a/Library/Homebrew/linkage_cache_store.rb b/Library/Homebrew/linkage_cache_store.rb
index b4b6dccfcf..408ad0f22f 100644
--- a/Library/Homebrew/linkage_cache_store.rb
+++ b/Library/Homebrew/linkage_cache_store.rb
@@ -3,11 +3,11 @@ require "cache_store"
 
 #
 # `LinkageCacheStore` provides methods to fetch and mutate linkage-specific data used
-# by the `brew linkage` command
+# by the `brew linkage` command.
 #
 class LinkageCacheStore < CacheStore
-  # @param  [String] keg_path
-  # @param  [CacheStoreDatabase] database
+  # @param keg_path [String]
+  # @param database [CacheStoreDatabase]
   # @return [nil]
   def initialize(keg_path, database)
     @keg_path = keg_path
@@ -24,7 +24,7 @@ class LinkageCacheStore < CacheStore
   # Inserts dylib-related information into the cache if it does not exist or
   # updates data into the linkage cache if it does exist
   #
-  # @param  [Hash] hash_values:  hash containing KVPs of { :type => Hash }
+  # @param hash_values [Hash] hash containing KVPs of { :type => Hash }
   # @return [nil]
   def update!(hash_values)
     hash_values.each_key do |type|
@@ -38,7 +38,7 @@ class LinkageCacheStore < CacheStore
     database.set @keg_path, hash_values
   end
 
-  # @param  [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)
@@ -64,7 +64,7 @@ class LinkageCacheStore < CacheStore
 
   HASH_LINKAGE_TYPES = [:keg_files_dylibs].freeze
 
-  # @param  [Symbol] type
+  # @param type [Symbol]
   # @return [Hash]
   def fetch_hash_values(type)
     keg_cache = database.get(@keg_path)
diff --git a/Library/Homebrew/messages.rb b/Library/Homebrew/messages.rb
index 5ee9901ded..55cf102645 100644
--- a/Library/Homebrew/messages.rb
+++ b/Library/Homebrew/messages.rb
@@ -1,5 +1,5 @@
 # A Messages object collects messages that may need to be displayed together
-# at the end of a multi-step `brew` command run
+# 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 cb3745c5d6..b98d908d2b 100644
--- a/Library/Homebrew/migrator.rb
+++ b/Library/Homebrew/migrator.rb
@@ -137,7 +137,7 @@ class Migrator
     @old_pin_link_record = old_pin_record.readlink if @pinned
   end
 
-  # Fix INSTALL_RECEIPTS for tap-migrated formula.
+  # Fix INSTALL_RECEIPTs for tap-migrated formula.
   def fix_tabs
     old_tabs.each do |tab|
       tab.tap = formula.tap
@@ -160,7 +160,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_RECEIPT's containing wrong information about tap,
+    # so there can be INSTALL_RECEIPTs 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.
diff --git a/Library/Homebrew/os/linux/elf.rb b/Library/Homebrew/os/linux/elf.rb
index 26dc0c659b..82789cb570 100644
--- a/Library/Homebrew/os/linux/elf.rb
+++ b/Library/Homebrew/os/linux/elf.rb
@@ -1,5 +1,5 @@
+# @see https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header
 module ELFShim
-  # See: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header
   MAGIC_NUMBER_OFFSET = 0
   MAGIC_NUMBER_ASCII = "\x7fELF".freeze
 
diff --git a/Library/Homebrew/os/mac.rb b/Library/Homebrew/os/mac.rb
index f936e31756..52ca596cd7 100644
--- a/Library/Homebrew/os/mac.rb
+++ b/Library/Homebrew/os/mac.rb
@@ -72,20 +72,23 @@ module OS
       @active_developer_dir ||= Utils.popen_read("/usr/bin/xcode-select", "-print-path").strip
     end
 
-    # If a specific SDK is requested
-    #   a) The requested SDK is returned, if it's installed.
-    #   b) If the requested SDK is not installed, the newest SDK (if any SDKs
+    # If a specific SDK is requested:
+    #
+    #   1. The requested SDK is returned, if it's installed.
+    #   2. If the requested SDK is not installed, the newest SDK (if any SDKs
     #      are available) is returned.
-    #   c) If no SDKs are available, nil is returned.
-    # If no specific SDK is requested
-    #   a) For Xcode >= 7, the latest SDK is returned even if the latest SDK is
+    #   3. If no SDKs are available, nil is returned.
+    #
+    # If no specific SDK is requested:
+    #
+    #   1. For Xcode >= 7, the latest SDK is returned even if the latest SDK is
     #      named after a newer OS version than the running OS. The
-    #      MACOSX_DEPLOYMENT_TARGET must be set to the OS for which you're
+    #      `MACOSX_DEPLOYMENT_TARGET` must be set to the OS for which you're
     #      actually building (usually the running OS version).
-    #      https://github.com/Homebrew/legacy-homebrew/pull/50355
-    #      https://developer.apple.com/library/ios/documentation/DeveloperTools/Conceptual/WhatsNewXcode/Articles/Introduction.html#//apple_ref/doc/uid/TP40004626
+    #      - https://github.com/Homebrew/legacy-homebrew/pull/50355
+    #      - https://developer.apple.com/library/ios/documentation/DeveloperTools/Conceptual/WhatsNewXcode/Articles/Introduction.html#//apple_ref/doc/uid/TP40004626
     #      Section "About SDKs and Simulator"
-    #   b) For Xcode < 7, proceed as if the SDK for the running OS version had
+    #   2. For Xcode < 7, proceed as if the SDK for the running OS version had
     #      specifically been requested according to the rules above.
 
     def sdk(v = nil)
@@ -98,7 +101,7 @@ module OS
       @locator.sdk_if_applicable(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
@@ -122,9 +125,10 @@ module OS
     end
 
     # See these issues for some history:
-    # https://github.com/Homebrew/legacy-homebrew/issues/13
-    # https://github.com/Homebrew/legacy-homebrew/issues/41
-    # https://github.com/Homebrew/legacy-homebrew/issues/48
+    #
+    # - https://github.com/Homebrew/legacy-homebrew/issues/13
+    # - https://github.com/Homebrew/legacy-homebrew/issues/41
+    # - https://github.com/Homebrew/legacy-homebrew/issues/48
     def macports_or_fink
       paths = []
 
diff --git a/Library/Homebrew/os/mac/xquartz.rb b/Library/Homebrew/os/mac/xquartz.rb
index a23701006f..8321d0ca37 100644
--- a/Library/Homebrew/os/mac/xquartz.rb
+++ b/Library/Homebrew/os/mac/xquartz.rb
@@ -60,8 +60,8 @@ module OS
         "2.7.11"
       end
 
-      # https://xquartz.macosforge.org/trac/wiki
-      # https://xquartz.macosforge.org/trac/wiki/Releases
+      # - https://xquartz.macosforge.org/trac/wiki
+      # - https://xquartz.macosforge.org/trac/wiki/Releases
       def latest_version
         case MacOS.version
         when "10.5"
@@ -114,8 +114,8 @@ module OS
       end
 
       # This should really be private, but for compatibility reasons it must
-      # remain public. New code should use MacOS::X11.bin, MacOS::X11.lib and
-      # MacOS::X11.include instead, as that accounts for Xcode-only systems.
+      # remain public. New code should use `MacOS::X11.bin`, `MacOS::X11.lib` and
+      # `MacOS::X11.include` instead, as that accounts for Xcode-only systems.
       def prefix
         @prefix ||= if Pathname.new("/opt/X11/lib/libpng.dylib").exist?
           Pathname.new("/opt/X11")
@@ -139,10 +139,10 @@ module OS
       end
 
       # If XQuartz and/or the CLT are installed, headers will be found under
-      # /opt/X11/include or /usr/X11/include. For Xcode-only systems, they are
-      # found in the SDK, so we use sdk_path for both the headers and libraries.
+      # `/opt/X11/include` or `/usr/X11/include`. For Xcode-only systems, they are
+      # found in the SDK, so we use {.sdk_path} for both the headers and libraries.
       # Confusingly, executables (e.g. config scripts) are only found under
-      # /opt/X11/bin or /usr/X11/bin in all cases.
+      # `/opt/X11/bin` or `/usr/X11/bin` in all cases.
       def effective_prefix
         if provided_by_apple? && Xcode.without_clt?
           Pathname.new("#{OS::Mac.sdk_path}/usr/X11")
diff --git a/Library/Homebrew/patch.rb b/Library/Homebrew/patch.rb
index a77e8b8eb2..3bb604bf82 100644
--- a/Library/Homebrew/patch.rb
+++ b/Library/Homebrew/patch.rb
@@ -162,7 +162,7 @@ class ExternalPatch
   end
 end
 
-# Legacy patches have no checksum and are not cached
+# Legacy patches have no checksum and are not cached.
 class LegacyPatch < ExternalPatch
   def initialize(strip, url)
     super(strip)
diff --git a/Library/Homebrew/requirement.rb b/Library/Homebrew/requirement.rb
index 8dcd865498..f9e8bf9581 100644
--- a/Library/Homebrew/requirement.rb
+++ b/Library/Homebrew/requirement.rb
@@ -49,7 +49,7 @@ class Requirement
     s
   end
 
-  # Overriding #satisfied? is unsupported.
+  # Overriding {#satisfied?} is unsupported.
   # Pass a block or boolean to the satisfy DSL method instead.
   def satisfied?
     satisfy = self.class.satisfy
@@ -61,7 +61,7 @@ class Requirement
     true
   end
 
-  # Overriding #fatal? is unsupported.
+  # Overriding {#fatal?} is unsupported.
   # Pass a boolean to the fatal DSL method instead.
   def fatal?
     self.class.fatal || false
@@ -77,7 +77,7 @@ class Requirement
     parent
   end
 
-  # Overriding #modify_build_environment is unsupported.
+  # Overriding {#modify_build_environment} is unsupported.
   # Pass a block to the env DSL method instead.
   def modify_build_environment
     satisfied?
@@ -196,7 +196,7 @@ class Requirement
 
   class << self
     # Expand the requirements of dependent recursively, optionally yielding
-    # [dependent, req] pairs to allow callers to apply arbitrary filters to
+    # `[dependent, req]` pairs to allow callers to apply arbitrary filters to
     # the list.
     # The default filter, which is applied when a block is not given, omits
     # optionals and recommendeds based on what the dependent has asked for.
diff --git a/Library/Homebrew/resource.rb b/Library/Homebrew/resource.rb
index 45fb18ad9b..81e820efac 100644
--- a/Library/Homebrew/resource.rb
+++ b/Library/Homebrew/resource.rb
@@ -61,10 +61,10 @@ class Resource
     downloader.clear_cache
   end
 
-  # Verifies download and unpacks it
+  # Verifies download and unpacks it.
   # The block may call `|resource,staging| staging.retain!` to retain the staging
   # directory. Subclasses that override stage should implement the tmp
-  # dir using Resource#mktemp so that works with all subtypes.
+  # dir using {Mktemp} so that works with all subtypes.
   def stage(target = nil, &block)
     unless target || block
       raise ArgumentError, "target directory or block is required"
@@ -91,8 +91,8 @@ class Resource
   end
 
   # If a target is given, unpack there; else unpack to a temp folder.
-  # If block is given, yield to that block with |stage|, where stage
-  # is a ResourceStagingContext.
+  # If block is given, yield to that block with `|stage|`, where stage
+  # is a {ResourceStageContext}.
   # A target or a block must be given, but not both.
   def unpack(target = nil)
     mktemp(download_name) do |staging|
@@ -210,15 +210,15 @@ class Resource
   end
 end
 
-# The context in which a Resource.stage() occurs. Supports access to both
-# the Resource and associated Mktemp in a single block argument. The interface
-# is back-compatible with Resource itself as used in that context.
+# 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.
 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/class_cop.rb b/Library/Homebrew/rubocops/class_cop.rb
index f6586e0054..0702e59fd5 100644
--- a/Library/Homebrew/rubocops/class_cop.rb
+++ b/Library/Homebrew/rubocops/class_cop.rb
@@ -68,7 +68,7 @@ module RuboCop
     end
 
     module FormulaAuditStrict
-      # - `test do ..end` should be meaningfully defined in the formula
+      # - `test do ..end` should be meaningfully defined in the formula.
       class Test < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           test = find_block(body_node, :test)
diff --git a/Library/Homebrew/rubocops/components_order_cop.rb b/Library/Homebrew/rubocops/components_order_cop.rb
index 9bde0804cb..efce883d8d 100644
--- a/Library/Homebrew/rubocops/components_order_cop.rb
+++ b/Library/Homebrew/rubocops/components_order_cop.rb
@@ -3,9 +3,9 @@ require "rubocops/extend/formula_cop"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop checks for correct order of components in a Formula
+      # This cop checks for correct order of components in Formulae.
       #
-      # - component_precedence_list has component hierarchy in a nested list
+      # - `component_precedence_list` has component hierarchy in a nested list
       #   where each sub array contains components' details which are at same precedence level
       class ComponentsOrder < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
@@ -96,9 +96,9 @@ module RuboCop
           end
         end
 
-        # Reorder two nodes in the source, using the corrector instance in autocorrect method
-        # Components of same type are grouped together when rewriting the source
-        # Linebreaks are introduced if components are of two different methods/blocks/multilines
+        # Reorder two nodes in the source, using the corrector instance in autocorrect method.
+        # Components of same type are grouped together when rewriting the source.
+        # Linebreaks are introduced if components are of two different methods/blocks/multilines.
         def reorder_components(corrector, node1, node2)
           # order_idx : node1's index in component_precedence_list
           # curr_p_idx: node1's index in preceding_comp_arr
diff --git a/Library/Homebrew/rubocops/components_redundancy_cop.rb b/Library/Homebrew/rubocops/components_redundancy_cop.rb
index a0fe004a89..881b4fee75 100644
--- a/Library/Homebrew/rubocops/components_redundancy_cop.rb
+++ b/Library/Homebrew/rubocops/components_redundancy_cop.rb
@@ -3,11 +3,11 @@ require "rubocops/extend/formula_cop"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop checks if redundant components are present and other component errors
+      # This cop checks if redundant components are present and other component errors.
       #
       # - `url|checksum|mirror` should be inside `stable` block
       # - `head` and `head do` should not be simultaneously present
-      # - `bottle :unneeded/:disable` and `bottle do` should not be simultaneously present
+      # - `bottle :unneeded`/`:disable` and `bottle do` should not be simultaneously present
       # - `stable do` should not be present without a `head` or `devel` spec
 
       class ComponentsRedundancy < FormulaCop
diff --git a/Library/Homebrew/rubocops/conflicts_cop.rb b/Library/Homebrew/rubocops/conflicts_cop.rb
index ff4d591074..8fa0547db6 100644
--- a/Library/Homebrew/rubocops/conflicts_cop.rb
+++ b/Library/Homebrew/rubocops/conflicts_cop.rb
@@ -4,7 +4,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.".freeze
diff --git a/Library/Homebrew/rubocops/dependency_order_cop.rb b/Library/Homebrew/rubocops/dependency_order_cop.rb
index 0648b22cd0..82934e146a 100644
--- a/Library/Homebrew/rubocops/dependency_order_cop.rb
+++ b/Library/Homebrew/rubocops/dependency_order_cop.rb
@@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop checks for correct order of `depends_on` in a Formula
+      # This cop checks for correct order of `depends_on` in Formulae.
       #
       # precedence order:
       # build-time > run-time > normal > recommended > optional
diff --git a/Library/Homebrew/rubocops/extend/formula_cop.rb b/Library/Homebrew/rubocops/extend/formula_cop.rb
index 7e11c4cd78..59b71d0156 100644
--- a/Library/Homebrew/rubocops/extend/formula_cop.rb
+++ b/Library/Homebrew/rubocops/extend/formula_cop.rb
@@ -30,7 +30,7 @@ module RuboCop
       end
 
       # 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)
         match_object = string_repr.match(pattern)
@@ -51,9 +51,9 @@ module RuboCop
         match_object
       end
 
-      # Yields to block when there is a match
-      # Parameters: urls : Array of url/mirror method call nodes
-      #             regex: regex pattern to match urls
+      # Yields to block when there is a match.
+      # @param urls [Array] url/mirror method call nodes
+      # @param regex [Regexp] pattern to match urls
       def audit_urls(urls, regex)
         urls.each do |url_node|
           url_string_node = parameters(url_node).first
@@ -104,8 +104,8 @@ module RuboCop
         node.each_child_node(:send).select { |method_node| method_name == method_node.method_name }
       end
 
-      # Returns an array of method call nodes matching method_name in every descendant of node
-      # Returns every method call if no method_name is passed
+      # Returns an array of method call nodes matching method_name in every descendant of node.
+      # Returns every method call if no method_name is passed.
       def find_every_method_call_by_name(node, method_name = nil)
         return if node.nil?
 
@@ -115,10 +115,11 @@ module RuboCop
         end
       end
 
-      # Returns array of function call nodes matching func_name in every descendant of node
-      #           Ex. 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 array of function call nodes matching func_name in every descendant of node.
+      #
+      # - 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
       def find_every_func_call_by_name(node, func_name = nil)
         return if node.nil?
 
@@ -139,12 +140,13 @@ module RuboCop
         end
       end
 
-      # Matches a method with a receiver,
-      # EX: to match `Formula.factory(name)`
-      # call `find_instance_method_call(node, "Formula", :factory)`
-      # EX: to match `build.head?`
-      # call `find_instance_method_call(node, :build, :head?)`
-      # yields to a block with matching method node
+      # Matches a method with a receiver.
+      #
+      # - e.g. to match `Formula.factory(name)`
+      #   call `find_instance_method_call(node, "Formula", :factory)`
+      # - e.g. to match `build.head?`
+      #   call `find_instance_method_call(node, :build, :head?)`
+      # - yields to a block with matching method node
       def find_instance_method_call(node, instance, method_name)
         methods = find_every_method_call_by_name(node, method_name)
         methods.each do |method|
@@ -160,10 +162,11 @@ module RuboCop
         end
       end
 
-      # Matches receiver part of method,
-      # EX: to match `ARGV.()`
-      # call `find_instance_call(node, "ARGV")`
-      # yields to a block with parent node of receiver
+      # Matches receiver part of method.
+      #
+      # - e.g. to match `ARGV.()`
+      #   call `find_instance_call(node, "ARGV")`
+      # - yields to a block with parent node of receiver
       def find_instance_call(node, name)
         node.each_descendant(:send) do |method_node|
           next if method_node.receiver.nil?
@@ -178,8 +181,8 @@ module RuboCop
         end
       end
 
-      # Returns nil if does not depend on dependency_name
-      # args: node - dependency_name - dependency's name
+      # 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?
         dependency_nodes = find_every_method_call_by_name(@body, :depends_on)
@@ -192,7 +195,7 @@ module RuboCop
         @offensive_node = dependency_nodes[idx]
       end
 
-      # Returns true if given dependency name and dependency type exist in given dependency method call node
+      # Returns true if given dependency name and dependency type exist in given dependency method call node.
       # TODO: Add case where key of hash is an array
       def depends_on_name_type?(node, name = nil, type = :required)
         if name
@@ -223,8 +226,8 @@ module RuboCop
         type_match && name_match
       end
 
-      # Find CONSTANTs in the source
-      # if block given, yield matching nodes
+      # Find CONSTANTs in the source.
+      # If block given, yield matching nodes.
       def find_const(node, const_name)
         return if node.nil?
 
@@ -284,7 +287,7 @@ module RuboCop
         node.each_child_node(:block).select { |block_node| block_name == block_node.method_name }
       end
 
-      # Returns an array of block nodes of any depth below node in AST
+      # Returns an array of block nodes of any depth below node in AST.
       # If a block is given then yields matching block node to the block!
       def find_all_blocks(node, block_name)
         return if node.nil?
@@ -298,8 +301,8 @@ module RuboCop
         end
       end
 
-      # Returns a method definition node with method_name
-      # Returns first method def if method_name is nil
+      # Returns a method definition node with method_name.
+      # Returns first method def if method_name is nil.
       def find_method_def(node, method_name = nil)
         return if node.nil?
 
@@ -332,8 +335,8 @@ module RuboCop
         false
       end
 
-      # Check if method_name is called among the direct children nodes in the given node
-      # Check if the node itself is the method
+      # Check if method_name is called among the direct children nodes in the given node.
+      # Check if the node itself is the method.
       def method_called?(node, method_name)
         if node.send_type? && node.method_name == method_name
           offending_node(node)
@@ -400,8 +403,8 @@ module RuboCop
       end
 
       # Returns true if the given parameters are present in method call
-      # and sets the method call as the offending node
-      # params can be string, symbol, array, hash, matching regex
+      # and sets the method call as the offending node.
+      # Params can be string, symbol, array, hash, matching regex.
       def parameters_passed?(method_node, *params)
         method_params = parameters(method_node)
         @offensive_node = method_node
diff --git a/Library/Homebrew/rubocops/formula_desc_cop.rb b/Library/Homebrew/rubocops/formula_desc_cop.rb
index c41313fbfe..4f856916de 100644
--- a/Library/Homebrew/rubocops/formula_desc_cop.rb
+++ b/Library/Homebrew/rubocops/formula_desc_cop.rb
@@ -4,7 +4,7 @@ require "extend/string"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits `desc` in Formulae
+      # This cop audits `desc` in Formulae.
       #
       # - Checks for existence of `desc`
       # - Checks if size of `desc` > 80
@@ -37,7 +37,7 @@ module RuboCop
     end
 
     module FormulaAuditStrict
-      # This cop audits `desc` in Formulae
+      # This cop audits `desc` in Formulae.
       #
       # - Checks for leading/trailing whitespace in `desc`
       # - Checks if `desc` begins with an article
diff --git a/Library/Homebrew/rubocops/homepage_cop.rb b/Library/Homebrew/rubocops/homepage_cop.rb
index 1c07f2896b..630037d4c7 100644
--- a/Library/Homebrew/rubocops/homepage_cop.rb
+++ b/Library/Homebrew/rubocops/homepage_cop.rb
@@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits `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)
diff --git a/Library/Homebrew/rubocops/lines_cop.rb b/Library/Homebrew/rubocops/lines_cop.rb
index ca5dbc4c1d..24a2637e61 100644
--- a/Library/Homebrew/rubocops/lines_cop.rb
+++ b/Library/Homebrew/rubocops/lines_cop.rb
@@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop checks for various miscellaneous Homebrew coding styles
+      # This cop checks for various miscellaneous Homebrew coding styles.
       class Lines < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, _body_node)
           [:automake, :ant, :autoconf, :emacs, :expat, :libtool, :mysql, :perl,
diff --git a/Library/Homebrew/rubocops/options_cop.rb b/Library/Homebrew/rubocops/options_cop.rb
index e16681e58b..ddd08e6866 100644
--- a/Library/Homebrew/rubocops/options_cop.rb
+++ b/Library/Homebrew/rubocops/options_cop.rb
@@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits `options` in Formulae
+      # This cop audits `options` in Formulae.
       class Options < FormulaCop
         DEPRECATION_MSG = "macOS has been 64-bit only since 10.6 so 32-bit options are deprecated.".freeze
 
diff --git a/Library/Homebrew/rubocops/patches_cop.rb b/Library/Homebrew/rubocops/patches_cop.rb
index b7b632ae16..db17cf102a 100644
--- a/Library/Homebrew/rubocops/patches_cop.rb
+++ b/Library/Homebrew/rubocops/patches_cop.rb
@@ -4,7 +4,7 @@ require "extend/string"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits patches in Formulae
+      # This cop audits patches in Formulae.
       class Patches < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body)
           external_patches = find_all_blocks(body, :patch)
diff --git a/Library/Homebrew/rubocops/urls_cop.rb b/Library/Homebrew/rubocops/urls_cop.rb
index ec8d7415ac..8ef40e9144 100644
--- a/Library/Homebrew/rubocops/urls_cop.rb
+++ b/Library/Homebrew/rubocops/urls_cop.rb
@@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits urls and mirrors in Formulae
+      # This cop audits URLs and mirrors in Formulae.
       class Urls < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           urls = find_every_func_call_by_name(body_node, :url)
diff --git a/Library/Homebrew/software_spec.rb b/Library/Homebrew/software_spec.rb
index b7a81d645d..59a351a1b5 100644
--- a/Library/Homebrew/software_spec.rb
+++ b/Library/Homebrew/software_spec.rb
@@ -359,7 +359,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/tap.rb b/Library/Homebrew/tap.rb
index 6a17b57330..19c32aa57b 100644
--- a/Library/Homebrew/tap.rb
+++ b/Library/Homebrew/tap.rb
@@ -2,7 +2,7 @@ require "extend/cachable"
 require "readall"
 require "description_cache_store"
 
-# a {Tap} is used to extend the formulae provided by Homebrew core.
+# 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
 # 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
@@ -55,7 +55,7 @@ class Tap
   extend Enumerable
 
   # The user name of this {Tap}. Usually, it's the GitHub username of
-  # this #{Tap}'s remote repository.
+  # this {Tap}'s remote repository.
   attr_reader :user
 
   # The repository name of this {Tap} without leading `homebrew-`.
@@ -87,7 +87,7 @@ class Tap
     @alias_reverse_table = nil
   end
 
-  # clear internal cache
+  # Clear internal cache
   def clear_cache
     @remote = nil
     @repo_var = nil
@@ -153,7 +153,7 @@ class Tap
     path.git_short_head
   end
 
-  # time since git last commit for this {Tap}.
+  # Time since git last commit for this {Tap}.
   def git_last_commit
     raise TapUnavailableError, name unless installed?
 
@@ -224,7 +224,7 @@ class Tap
     false
   end
 
-  # install this {Tap}.
+  # Install this {Tap}.
   #
   # @param [Hash] options
   # @option options [String] :clone_target If passed, it will be used as the clone remote.
@@ -324,7 +324,7 @@ class Tap
     Utils::Link.link_completions(path, command)
   end
 
-  # uninstall this {Tap}.
+  # Uninstall this {Tap}.
   def uninstall
     require "descriptions"
     raise TapUnavailableError, name unless installed?
@@ -354,7 +354,7 @@ class Tap
     remote.casecmp(default_remote).nonzero?
   end
 
-  # path to the directory of all {Formula} files for this {Tap}.
+  # Path to the directory of all {Formula} files for this {Tap}.
   def formula_dir
     @formula_dir ||= potential_formula_dirs.find(&:directory?) || path/"Formula"
   end
@@ -363,7 +363,7 @@ class Tap
     @potential_formula_dirs ||= [path/"Formula", path/"HomebrewFormula", path].freeze
   end
 
-  # path to the directory of all {Cask} files for this {Tap}.
+  # Path to the directory of all {Cask} files for this {Tap}.
   def cask_dir
     @cask_dir ||= path/"Casks"
   end
@@ -386,7 +386,7 @@ class Tap
     contents
   end
 
-  # an array of all {Formula} files of this {Tap}.
+  # An array of all {Formula} files of this {Tap}.
   def formula_files
     @formula_files ||= if formula_dir.directory?
       formula_dir.children.select(&method(:ruby_file?))
@@ -395,7 +395,7 @@ class Tap
     end
   end
 
-  # an array of all {Cask} files of this {Tap}.
+  # An array of all {Cask} files of this {Tap}.
   def cask_files
     @cask_files ||= if cask_dir.directory?
       cask_dir.children.select(&method(:ruby_file?))
@@ -428,7 +428,7 @@ class Tap
     ruby_file?(file) && file.parent == cask_dir
   end
 
-  # an array of all {Formula} names of this {Tap}.
+  # An array of all {Formula} names of this {Tap}.
   def formula_names
     @formula_names ||= formula_files.map { |f| formula_file_to_name(f) }
   end
@@ -487,7 +487,7 @@ class Tap
       (file.executable? || file.extname == ".rb")
   end
 
-  # an array of all commands files of this {Tap}.
+  # An array of all commands files of this {Tap}.
   def command_files
     @command_files ||= if command_dir.directory?
       command_dir.children.select(&method(:command_file?))
@@ -509,7 +509,7 @@ class Tap
     @pinned = pinned_symlink_path.directory?
   end
 
-  # pin this {Tap}.
+  # Pin this {Tap}.
   def pin
     raise TapUnavailableError, name unless installed?
     raise TapPinStatusError.new(name, true) if pinned?
@@ -518,7 +518,7 @@ class Tap
     @pinned = true
   end
 
-  # unpin this {Tap}.
+  # Unpin this {Tap}.
   def unpin
     raise TapUnavailableError, name unless installed?
     raise TapPinStatusError.new(name, false) unless pinned?
@@ -591,12 +591,12 @@ class Tap
     end
   end
 
-  # an array of all installed {Tap} names.
+  # An array of all installed {Tap} names.
   def self.names
     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
@@ -633,7 +633,7 @@ class Tap
   end
 end
 
-# A specialized {Tap} class for the core formulae
+# A specialized {Tap} class for the core formulae.
 class CoreTap < Tap
   def default_remote
     "https://github.com/Homebrew/homebrew-core".freeze
@@ -722,7 +722,7 @@ class CoreTap < Tap
   end
 end
 
-# Permanent configuration per {Tap} using `git-config(1)`
+# Permanent configuration per {Tap} using `git-config(1)`.
 class TapConfig
   attr_reader :tap
 
diff --git a/Library/Homebrew/utils.rb b/Library/Homebrew/utils.rb
index c34ec720cf..8d20dc2444 100644
--- a/Library/Homebrew/utils.rb
+++ b/Library/Homebrew/utils.rb
@@ -303,7 +303,7 @@ def safe_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
@@ -504,9 +504,9 @@ end
 # Calls the given block with the passed environment variables
 # added to ENV, then restores ENV afterwards.
 # Example:
-# with_env(PATH: "/bin") do
+# 
with_env(PATH: "/bin") do
 #   system "echo $PATH"
-# end
+# end

 #
 # Note that this method is *not* thread-safe - other threads
 # which happen to be scheduled during the block will also
diff --git a/Library/Homebrew/utils/inreplace.rb b/Library/Homebrew/utils/inreplace.rb
index f7d06db5aa..67881953d0 100644
--- a/Library/Homebrew/utils/inreplace.rb
+++ b/Library/Homebrew/utils/inreplace.rb
@@ -13,8 +13,9 @@ module Utils
     # 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
-    # HOMEBREW_PREFIX is available in the embedded patch.
-    # inreplace supports regular expressions.
+    # `HOMEBREW_PREFIX` is available in the embedded patch.
+    #
+    # `inreplace` supports regular expressions:
     # 
inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"

     def inreplace(paths, before = nil, after = nil, audit_result = true)
       errors = {}
diff --git a/Library/Homebrew/utils/shell.rb b/Library/Homebrew/utils/shell.rb
index 9a886ca40d..d53741603e 100644
--- a/Library/Homebrew/utils/shell.rb
+++ b/Library/Homebrew/utils/shell.rb
@@ -35,7 +35,7 @@ module Utils
       end
     end
 
-    # return the shell profile file based on users' preferred shell
+    # return the shell profile file based on user's preferred shell
     def profile
       SHELL_PROFILE_MAP.fetch(preferred, "~/.bash_profile")
     end