From 480e264d9a5f8ae88d9fa768cf0db7f7a7c601db Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Tue, 30 Apr 2024 11:10:23 +0200
Subject: [PATCH] Lint Ruby docs.

---
 .github/ISSUE_TEMPLATE.md                     |   2 +-
 .github/workflows/docs.yml                    |  19 ++-
 .vale.ini                                     |   5 +-
 Library/Homebrew/abstract_command.rb          |   3 +-
 Library/Homebrew/build_environment.rb         |   2 +-
 Library/Homebrew/cask/audit.rb                |   4 +-
 Library/Homebrew/cleaner.rb                   |  37 +++---
 Library/Homebrew/cleanup.rb                   |   6 +-
 Library/Homebrew/cmd/--prefix.rb              |   2 +-
 Library/Homebrew/cmd/outdated.rb              |   2 +-
 Library/Homebrew/dependencies_helpers.rb      |   2 +-
 Library/Homebrew/dependency_collector.rb      |  14 +--
 Library/Homebrew/dev-cmd/pr-pull.rb           |   6 +-
 Library/Homebrew/dev-cmd/tap-new.rb           |   3 +
 Library/Homebrew/dev-cmd/tests.rb             |   7 +-
 Library/Homebrew/dev-cmd/update-test.rb       |   2 +-
 Library/Homebrew/diagnostic.rb                |  12 +-
 Library/Homebrew/download_strategy.rb         |   4 +-
 Library/Homebrew/extend/ENV.rb                |  12 +-
 Library/Homebrew/extend/os/linux/install.rb   |   4 +-
 Library/Homebrew/extend/os/mac/diagnostic.rb  |   2 +-
 .../extend/os/mac/formula_cellar_checks.rb    |   2 +-
 Library/Homebrew/fetch.rb                     |   2 +-
 Library/Homebrew/formula_assertions.rb        |   6 +-
 Library/Homebrew/formula_creator.rb           |   7 +-
 Library/Homebrew/formulary.rb                 |  12 +-
 Library/Homebrew/github_packages.rb           |  18 +--
 Library/Homebrew/keg.rb                       |   4 +-
 Library/Homebrew/language/python.rb           |   4 +-
 Library/Homebrew/livecheck/strategy/git.rb    |   2 +-
 Library/Homebrew/livecheck/strategy/json.rb   |   2 +-
 Library/Homebrew/livecheck/strategy/xml.rb    |   2 +-
 Library/Homebrew/livecheck/strategy/yaml.rb   |   2 +-
 Library/Homebrew/manpages.rb                  |   2 +-
 Library/Homebrew/mktemp.rb                    |   2 +-
 Library/Homebrew/os/mac/sdk.rb                |   4 +-
 Library/Homebrew/resource.rb                  |   4 +-
 .../rubocops/cask/array_alphabetization.rb    |   2 +-
 Library/Homebrew/rubocops/cask/url.rb         |   2 +-
 Library/Homebrew/rubocops/compact_blank.rb    |   2 +-
 Library/Homebrew/rubocops/homepage.rb         |   4 +-
 Library/Homebrew/rubocops/urls.rb             |   8 +-
 Library/Homebrew/software_spec.rb             |   6 +-
 Library/Homebrew/startup/config.rb            |   4 +-
 Library/Homebrew/tap.rb                       |   4 +-
 .../cask/artifact/abstract_artifact_spec.rb   |   2 +-
 Library/Homebrew/test/cask/dsl_spec.rb        |   2 +-
 .../test/language/python/virtualenv_spec.rb   |   2 +-
 .../livecheck/strategy/extract_plist_spec.rb  |   2 +-
 .../test/livecheck/strategy/sparkle_spec.rb   |   2 +-
 .../os/linux/dependency_collector_spec.rb     |   4 +-
 .../Homebrew/test/rubocops/caveats_spec.rb    |   2 +-
 Library/Homebrew/test/spec_helper.rb          |   2 +-
 Library/Homebrew/test/utils/gzip_spec.rb      |   2 +-
 Library/Homebrew/test/utils/pypi_spec.rb      |   2 +-
 Library/Homebrew/utils/curl.rb                |   4 +-
 Library/Homebrew/utils/gems.rb                |   2 +-
 Library/Homebrew/utils/pypi.rb                |   2 +-
 Library/Homebrew/utils/shell.rb               |  10 +-
 Library/Homebrew/version.rb                   | 112 +++++++++---------
 Library/Homebrew/warnings.rb                  |   3 +
 completions/fish/brew.fish                    |   6 +-
 completions/zsh/_brew                         |   6 +-
 docs/External-Commands.md                     |   2 +-
 docs/Formula-Cookbook.md                      |   2 +-
 docs/How-To-Organize-AGM.md                   |   2 +-
 docs/Manpage.md                               |  12 +-
 docs/Taps.md                                  |  13 +-
 docs/governance/2021-agm-minutes.md           |   2 +-
 docs/vale-styles/Homebrew/Abbreviations.yml   |   8 +-
 docs/vale-styles/Homebrew/Spacing.yml         |   4 +-
 docs/vale-styles/Homebrew/Terms.yml           |   6 +-
 manpages/README.md                            |   2 +-
 manpages/brew.1                               |  10 +-
 74 files changed, 263 insertions(+), 224 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
index 09af8ebef8..ff2c5e3577 100644
--- a/.github/ISSUE_TEMPLATE.md
+++ b/.github/ISSUE_TEMPLATE.md
@@ -1 +1 @@
-# Please fill out one of the templates on: https://github.com/Homebrew/brew/issues/new/choose or we will close it without comment.
+Please fill out one of the templates on https://github.com/Homebrew/brew/issues/new/choose or we will close your issue without comment.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 30e4f549ce..1a62b3a1cb 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -25,9 +25,22 @@ jobs:
       - name: Install vale
         run: brew install vale
 
-      - name: Run vale for docs linting
-        working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs
-        run: vale .
+      - name: Lint docs
+        working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}
+        run: |
+          set -euo pipefail
+
+          # Avoid failing on broken symlinks.
+          rm Library/Homebrew/os/mac/pkgconfig/fuse/fuse.pc
+          rm Library/Homebrew/os/mac/pkgconfig/fuse/osxfuse.pc
+
+          # No ignore support (https://github.com/errata-ai/vale/issues/131).
+          rm -r Library/Homebrew/vendor
+
+          vale .
+
+          # Restore removed files.
+          git reset --hard
 
       - name: Install Ruby
         uses: ruby/setup-ruby@1198b074305f9356bd56dd4b311757cc0dab2f1c # v1.175.1
diff --git a/.vale.ini b/.vale.ini
index 8aeb075101..13f035651a 100644
--- a/.vale.ini
+++ b/.vale.ini
@@ -1,4 +1,7 @@
 StylesPath = ./docs/vale-styles
 
-[*.md]
+[formats]
+rb = md
+
+[*.{md,rb}]
 BasedOnStyles = Homebrew
diff --git a/Library/Homebrew/abstract_command.rb b/Library/Homebrew/abstract_command.rb
index 9d11837cc1..e24c7ae719 100644
--- a/Library/Homebrew/abstract_command.rb
+++ b/Library/Homebrew/abstract_command.rb
@@ -6,9 +6,10 @@ require "cli/parser"
 module Homebrew
   # Subclass this to implement a `brew` command. This is preferred to declaring a named function in the `Homebrew`
   # module, because:
+  #
   # - Each Command lives in an isolated namespace.
   # - Each Command implements a defined interface.
-  # - `args` is available as an ivar, and thus does not need to be passed as an argument to helper methods.
+  # - `args` is available as an instance method and thus does not need to be passed as an argument to helper methods.
   # - Subclasses no longer need to reference `CLI::Parser` or parse args explicitly.
   #
   # To subclass, implement a `run` method and provide a `cmd_args` block to document the command and its allowed args.
diff --git a/Library/Homebrew/build_environment.rb b/Library/Homebrew/build_environment.rb
index a07db8e88b..d2028f2c62 100644
--- a/Library/Homebrew/build_environment.rb
+++ b/Library/Homebrew/build_environment.rb
@@ -28,7 +28,7 @@ class BuildEnvironment
   # DSL for specifying build environment settings.
   module DSL
     # Initialise @env for each class which may use this DSL (e.g. each formula subclass).
-    # `env` may never be called, and it needs to be initialised before the class is frozen.
+    # `env` may never be called and it needs to be initialised before the class is frozen.
     def inherited(child)
       super
       child.instance_eval do
diff --git a/Library/Homebrew/cask/audit.rb b/Library/Homebrew/cask/audit.rb
index 067e775c9c..bb3de17d02 100644
--- a/Library/Homebrew/cask/audit.rb
+++ b/Library/Homebrew/cask/audit.rb
@@ -685,7 +685,7 @@ module Cask
 
     sig { void }
     def audit_github_repository_archived
-      # Deprecated/disabled casks may have an archived repo.
+      # Deprecated/disabled casks may have an archived repository.
       return if cask.discontinued? || cask.deprecated? || cask.disabled?
 
       user, repo = get_repo_data(%r{https?://github\.com/([^/]+)/([^/]+)/?.*}) if online?
@@ -699,7 +699,7 @@ module Cask
 
     sig { void }
     def audit_gitlab_repository_archived
-      # Deprecated/disabled casks may have an archived repo.
+      # Deprecated/disabled casks may have an archived repository.
       return if cask.discontinued? || cask.deprecated? || cask.disabled?
 
       user, repo = get_repo_data(%r{https?://gitlab\.com/([^/]+)/([^/]+)/?.*}) if online?
diff --git a/Library/Homebrew/cleaner.rb b/Library/Homebrew/cleaner.rb
index 5f9217aeb3..79f2734f18 100644
--- a/Library/Homebrew/cleaner.rb
+++ b/Library/Homebrew/cleaner.rb
@@ -25,27 +25,28 @@ class Cleaner
   def clean
     ObserverPathnameExtension.reset_counts!
 
-    # Many formulae include 'lib/charset.alias', but it is not strictly needed
-    # and will conflict if more than one formula provides it
+    # Many formulae include `lib/charset.alias`, but it is not strictly needed
+    # and will conflict if more than one formula provides it.
     observe_file_removal @formula.lib/"charset.alias"
 
     [@formula.bin, @formula.sbin, @formula.lib].each { |dir| clean_dir(dir) if dir.exist? }
 
-    # Get rid of any info 'dir' files, so they don't conflict at the link stage
+    # Get rid of any info `dir` files, so they don't conflict at the link stage.
     #
-    # The 'dir' files come in at least 3 locations:
+    # The `dir` files come in at least 3 locations:
     #
-    # 1. 'info/dir'
-    # 2. 'info/#{name}/dir'
-    # 3. 'info/#{arch}/dir'
+    # 1. `info/dir`
+    # 2. `info/#{name}/dir`
+    # 3. `info/#{arch}/dir`
     #
-    # Of these 3 only 'info/#{name}/dir' is safe to keep since the rest will
+    # Of these 3 only `info/#{name}/dir` is safe to keep since the rest will
     # conflict with other formulae because they use a shared location.
     #
-    # See [cleaner: recursively delete info `dir`s by gromgit · Pull Request
-    # #11597][1], [emacs 28.1 bottle does not contain `dir` file · Issue
-    # #100190][2], and [Keep `info/#{f.name}/dir` files in cleaner by
-    # timvisher][3] for more info.
+    # See
+    # [cleaner: recursively delete info `dir`s][1],
+    # [emacs 28.1 bottle does not contain `dir` file][2] and
+    # [Keep `info/#{f.name}/dir` files in cleaner][3]
+    # for more info.
     #
     # [1]: https://github.com/Homebrew/brew/pull/11597
     # [2]: https://github.com/Homebrew/homebrew-core/issues/100190
@@ -114,15 +115,15 @@ class Cleaner
   # created as part of installing any Perl module.
   PERL_BASENAMES = Set.new(%w[perllocal.pod .packlist]).freeze
 
-  # Clean a top-level (bin, sbin, lib) directory, recursively, by fixing file
+  # Clean a top-level (`bin`, `sbin`, `lib`) directory, recursively, by fixing file
   # permissions and removing .la files, unless the files (or parent
   # directories) are protected by skip_clean.
   #
-  # bin and sbin should not have any subdirectories; if either do that is
-  # caught as an audit warning
+  # `bin` and `sbin` should not have any subdirectories; if either do that is
+  # caught as an audit warning.
   #
-  # lib may have a large directory tree (see Erlang for instance), and
-  # clean_dir applies cleaning rules to the entire tree
+  # `lib` may have a large directory tree (see Erlang for instance) and
+  # clean_dir applies cleaning rules to the entire tree.
   sig { params(directory: Pathname).void }
   def clean_dir(directory)
     directory.find do |path|
@@ -137,7 +138,7 @@ class Cleaner
       elsif path.symlink?
         # Skip it.
       else
-        # Set permissions for executables and non-executables
+        # Set permissions for executables and non-executables.
         perms = if executable_path?(path)
           0555
         else
diff --git a/Library/Homebrew/cleanup.rb b/Library/Homebrew/cleanup.rb
index ae44d69f9a..fd0c2d30de 100644
--- a/Library/Homebrew/cleanup.rb
+++ b/Library/Homebrew/cleanup.rb
@@ -376,7 +376,7 @@ module Homebrew
     def cache_files
       files = cache.directory? ? cache.children : []
       cask_files = (cache/"Cask").directory? ? (cache/"Cask").children : []
-      api_source_files = (cache/"api-source").glob("*/*/*/*/*") # org/repo/git_head/type/file.rb
+      api_source_files = (cache/"api-source").glob("*/*/*/*/*") # `<org>/<repo>/<git_head>/<type>/<token>.rb`
       gh_actions_artifacts = (cache/"gh-actions-artifact").directory? ? (cache/"gh-actions-artifact").children : []
 
       files.map { |path| { path:, type: nil } } +
@@ -571,8 +571,8 @@ module Homebrew
       HOMEBREW_PREFIX.glob("lib/python*/site-packages").each do |site_packages|
         site_packages.each_child do |child|
           next unless child.directory?
-          # TODO: Work out a sensible way to clean up pip's, setuptools', and wheel's
-          #       {dist,site}-info directories. Alternatively, consider always removing
+          # TODO: Work out a sensible way to clean up `pip`'s, `setuptools`' and `wheel`'s
+          #       `{dist,site}-info` directories. Alternatively, consider always removing
           #       all `-info` directories, because we may not be making use of them.
           next if child.basename.to_s.end_with?("-info")
 
diff --git a/Library/Homebrew/cmd/--prefix.rb b/Library/Homebrew/cmd/--prefix.rb
index eb44d4ef35..c01fa7dc17 100644
--- a/Library/Homebrew/cmd/--prefix.rb
+++ b/Library/Homebrew/cmd/--prefix.rb
@@ -95,7 +95,7 @@ module Homebrew
         dirs  = HOMEBREW_PREFIX.subdirs.map { |dir| dir.basename.to_s }
         dirs -= %w[Library Cellar Caskroom .git]
 
-        # Exclude cache, logs, and repository, if they are located under the prefix.
+        # Exclude cache, logs and repository, if they are located under the prefix.
         [HOMEBREW_CACHE, HOMEBREW_LOGS, HOMEBREW_REPOSITORY].each do |dir|
           dirs.delete dir.relative_path_from(HOMEBREW_PREFIX).to_s
         end
diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb
index a6a7eb6a3e..72170324a6 100644
--- a/Library/Homebrew/cmd/outdated.rb
+++ b/Library/Homebrew/cmd/outdated.rb
@@ -13,7 +13,7 @@ module Homebrew
       cmd_args do
         description <<~EOS
           List installed casks and formulae that have an updated version available. By default, version
-          information is displayed in interactive shells, and suppressed otherwise.
+          information is displayed in interactive shells and suppressed otherwise.
         EOS
         switch "-q", "--quiet",
                description: "List only the names of outdated kegs (takes precedence over `--verbose`)."
diff --git a/Library/Homebrew/dependencies_helpers.rb b/Library/Homebrew/dependencies_helpers.rb
index fa6b3b2b4b..7b0f4dc0e5 100644
--- a/Library/Homebrew/dependencies_helpers.rb
+++ b/Library/Homebrew/dependencies_helpers.rb
@@ -33,7 +33,7 @@ module DependenciesHelpers
       end
 
       # If a tap isn't installed, we can't find the dependencies of one of
-      # its formulae, and an exception will be thrown if we try.
+      # its formulae and an exception will be thrown if we try.
       Dependency.keep_but_prune_recursive_deps if klass == Dependency && dep.tap && !dep.tap.installed?
     end
   end
diff --git a/Library/Homebrew/dependency_collector.rb b/Library/Homebrew/dependency_collector.rb
index 4d03ada7f8..8a27e3958a 100644
--- a/Library/Homebrew/dependency_collector.rb
+++ b/Library/Homebrew/dependency_collector.rb
@@ -7,13 +7,13 @@ require "requirement"
 require "requirements"
 require "extend/cachable"
 
-## A dependency is a formula that another formula needs to install.
-## A requirement is something other than a formula that another formula
-## needs to be present. This includes external language modules,
-## command-line tools in the path, or any arbitrary predicate.
-##
-## The `depends_on` method in the formula DSL is used to declare
-## dependencies and requirements.
+# A dependency is a formula that another formula needs to install.
+# A requirement is something other than a formula that another formula
+# needs to be present. This includes external language modules,
+# command-line tools in the path, or any arbitrary predicate.
+#
+# The `depends_on` method in the formula DSL is used to declare
+# dependencies and requirements.
 
 # This class is used by `depends_on` in the formula DSL to turn dependency
 # specifications into the proper kinds of dependencies and requirements.
diff --git a/Library/Homebrew/dev-cmd/pr-pull.rb b/Library/Homebrew/dev-cmd/pr-pull.rb
index c08badc32f..6e6210acd0 100644
--- a/Library/Homebrew/dev-cmd/pr-pull.rb
+++ b/Library/Homebrew/dev-cmd/pr-pull.rb
@@ -15,7 +15,7 @@ module Homebrew
 
       cmd_args do
         description <<~EOS
-          Download and publish bottles, and apply the bottle commit from a
+          Download and publish bottles and apply the bottle commit from a
           pull request with artifacts generated by GitHub Actions.
           Requires write access to the repository.
         EOS
@@ -187,7 +187,7 @@ module Homebrew
         end
       end
 
-      # Separates a commit message into subject, body, and trailers.
+      # Separates a commit message into subject, body and trailers.
       def separate_commit_message(message)
         subject = message.lines.first.strip
 
@@ -337,7 +337,7 @@ module Homebrew
         new_package = package_file.read
         bump_subject = determine_bump_subject(old_package, new_package, package_file, reason:)
 
-        # Commit with the new subject, body, and trailers.
+        # Commit with the new subject, body and trailers.
         safe_system("git", "-C", git_repo.pathname, "commit", "--quiet",
                     "-m", bump_subject, "-m", messages.join("\n"), "-m", trailers.join("\n"),
                     "--author", original_author, "--date", original_date, "--", file)
diff --git a/Library/Homebrew/dev-cmd/tap-new.rb b/Library/Homebrew/dev-cmd/tap-new.rb
index 84d0d415a6..8278731722 100644
--- a/Library/Homebrew/dev-cmd/tap-new.rb
+++ b/Library/Homebrew/dev-cmd/tap-new.rb
@@ -46,6 +46,8 @@ module Homebrew
 
         (tap.path/"Formula").mkpath
 
+        # FIXME: https://github.com/errata-ai/vale/issues/818
+        # <!-- vale off -->
         readme = <<~MARKDOWN
           # #{titleized_user} #{titleized_repo}
 
@@ -59,6 +61,7 @@ module Homebrew
 
           `brew help`, `man brew` or check [Homebrew's documentation](https://docs.brew.sh).
         MARKDOWN
+        # <!-- vale on -->
         write_path(tap, "README.md", readme)
 
         actions_main = <<~YAML
diff --git a/Library/Homebrew/dev-cmd/tests.rb b/Library/Homebrew/dev-cmd/tests.rb
index 0a3a99b2d1..60845d6cc2 100644
--- a/Library/Homebrew/dev-cmd/tests.rb
+++ b/Library/Homebrew/dev-cmd/tests.rb
@@ -22,13 +22,13 @@ module Homebrew
                description: "Include tests that use the GitHub API and tests that use any of the taps for " \
                             "official external commands."
         switch "--debug",
-               description: "Enable debugging using ruby/debug, or surface the standard `odebug` output."
+               description: "Enable debugging using `ruby/debug`, or surface the standard `odebug` output."
         switch "--changed",
                description: "Only runs tests on files that were changed from the master branch."
         switch "--fail-fast",
                description: "Exit early on the first failing test."
         flag   "--only=",
-               description: "Run only <test_script>`_spec.rb`. Appending `:`<line_number> will start at a " \
+               description: "Run only `<test_script>_spec.rb`. Appending `:<line_number>` will start at a " \
                             "specific line."
         flag   "--profile=",
                description: "Run the test suite serially to find the <n> slowest tests."
@@ -145,7 +145,10 @@ module Homebrew
           end
 
           # Workaround for:
+          #
+          # ```
           # ruby: no -r allowed while running setuid (SecurityError)
+          # ```
           Process::UID.change_privilege(Process.euid) if Process.euid != Process.uid
 
           if parallel
diff --git a/Library/Homebrew/dev-cmd/update-test.rb b/Library/Homebrew/dev-cmd/update-test.rb
index c2b637f686..1b9193097e 100644
--- a/Library/Homebrew/dev-cmd/update-test.rb
+++ b/Library/Homebrew/dev-cmd/update-test.rb
@@ -116,7 +116,7 @@ module Homebrew
           # update ENV["PATH"]
           ENV["PATH"] = PATH.new(ENV.fetch("PATH")).prepend(curdir/"bin").to_s
 
-          # run brew help to install portable-ruby (if needed)
+          # Run `brew help` to install `portable-ruby` (if needed).
           quiet_system "brew", "help"
 
           # run brew update
diff --git a/Library/Homebrew/diagnostic.rb b/Library/Homebrew/diagnostic.rb
index c764977dd8..be12eb049c 100644
--- a/Library/Homebrew/diagnostic.rb
+++ b/Library/Homebrew/diagnostic.rb
@@ -221,7 +221,7 @@ module Homebrew
         __check_stray_files "/usr/local/lib", "*.dylib", allow_list, <<~EOS
           Unbrewed dylibs were found in /usr/local/lib.
           If you didn't put them there on purpose they could cause problems when
-          building Homebrew formulae, and may need to be deleted.
+          building Homebrew formulae and may need to be deleted.
 
           Unexpected dylibs:
         EOS
@@ -246,7 +246,7 @@ module Homebrew
         __check_stray_files "/usr/local/lib", "*.a", allow_list, <<~EOS
           Unbrewed static libraries were found in /usr/local/lib.
           If you didn't put them there on purpose they could cause problems when
-          building Homebrew formulae, and may need to be deleted.
+          building Homebrew formulae and may need to be deleted.
 
           Unexpected static libraries:
         EOS
@@ -266,7 +266,7 @@ module Homebrew
         __check_stray_files "/usr/local/lib/pkgconfig", "*.pc", allow_list, <<~EOS
           Unbrewed '.pc' files were found in /usr/local/lib/pkgconfig.
           If you didn't put them there on purpose they could cause problems when
-          building Homebrew formulae, and may need to be deleted.
+          building Homebrew formulae and may need to be deleted.
 
           Unexpected '.pc' files:
         EOS
@@ -287,7 +287,7 @@ module Homebrew
         __check_stray_files "/usr/local/lib", "*.la", allow_list, <<~EOS
           Unbrewed '.la' files were found in /usr/local/lib.
           If you didn't put them there on purpose they could cause problems when
-          building Homebrew formulae, and may need to be deleted.
+          building Homebrew formulae and may need to be deleted.
 
           Unexpected '.la' files:
         EOS
@@ -306,7 +306,7 @@ module Homebrew
         __check_stray_files "/usr/local/include", "**/*.h", allow_list, <<~EOS
           Unbrewed header files were found in /usr/local/include.
           If you didn't put them there on purpose they could cause problems when
-          building Homebrew formulae, and may need to be deleted.
+          building Homebrew formulae and may need to be deleted.
 
           Unexpected header files:
         EOS
@@ -491,7 +491,7 @@ module Homebrew
 
         <<~EOS
           Git could not be found in your PATH.
-          Homebrew uses Git for several internal functions, and some formulae use Git
+          Homebrew uses Git for several internal functions and some formulae use Git
           checkouts instead of stable tarballs. You may want to install Git:
             brew install git
         EOS
diff --git a/Library/Homebrew/download_strategy.rb b/Library/Homebrew/download_strategy.rb
index 162ae6fe76..e4c9aa0038 100644
--- a/Library/Homebrew/download_strategy.rb
+++ b/Library/Homebrew/download_strategy.rb
@@ -931,8 +931,8 @@ class GitDownloadStrategy < VCSDownloadStrategy
 
     args << "--no-checkout" << "--filter=blob:none" if partial_clone_sparse_checkout?
 
-    args << "--config" << "advice.detachedHead=false" # silences detached head warning
-    args << "--config" << "core.fsmonitor=false" # prevent fsmonitor from watching this repo
+    args << "--config" << "advice.detachedHead=false" # Silences “detached head” warning.
+    args << "--config" << "core.fsmonitor=false" # Prevent `fsmonitor` from watching this repository.
     args << @url << cached_location.to_s
   end
 
diff --git a/Library/Homebrew/extend/ENV.rb b/Library/Homebrew/extend/ENV.rb
index 051acbb11a..b7a9afb644 100644
--- a/Library/Homebrew/extend/ENV.rb
+++ b/Library/Homebrew/extend/ENV.rb
@@ -17,10 +17,16 @@ module Kernel
   private :superenv?
 end
 
+# <!-- vale off -->
 # @!parse
-#  # ENV is not actually a class, but this makes `YARD` happy
-#  # @see https://rubydoc.info/stdlib/core/ENV ENV core documentation
-#  class ENV; end
+#   # `ENV` is not actually a class, but this makes YARD happy
+#   # @see https://rubydoc.info/stdlib/core/ENV
+#   #   <code>ENV</code> core documentation
+#   # @see Superenv
+#   # @see Stdenv
+#   class ENV; end
+# <!-- vale on -->
+
 module EnvActivation
   sig { params(env: T.nilable(String)).void }
   def activate_extensions!(env: nil)
diff --git a/Library/Homebrew/extend/os/linux/install.rb b/Library/Homebrew/extend/os/linux/install.rb
index 943ae7bea9..e4476a00b8 100644
--- a/Library/Homebrew/extend/os/linux/install.rb
+++ b/Library/Homebrew/extend/os/linux/install.rb
@@ -4,7 +4,7 @@
 module Homebrew
   module Install
     # This is a list of known paths to the host dynamic linker on Linux if
-    # the host glibc is new enough.  The symlink_ld_so method will fail if
+    # the host glibc is new enough. The symlink_ld_so method will fail if
     # the host linker cannot be found in this list.
     DYNAMIC_LINKERS = %w[
       /lib64/ld-linux-x86-64.so.2
@@ -19,7 +19,7 @@ module Homebrew
     private_constant :DYNAMIC_LINKERS
 
     # We link GCC runtime libraries that are not specifically used for Fortran,
-    # which are linked by the GCC formula.  We only use the versioned shared libraries
+    # which are linked by the GCC formula. We only use the versioned shared libraries
     # as the other shared and static libraries are only used at build time where
     # GCC can find its own libraries.
     GCC_RUNTIME_LIBS = %w[
diff --git a/Library/Homebrew/extend/os/mac/diagnostic.rb b/Library/Homebrew/extend/os/mac/diagnostic.rb
index 98774d3a92..6733fc0b34 100644
--- a/Library/Homebrew/extend/os/mac/diagnostic.rb
+++ b/Library/Homebrew/extend/os/mac/diagnostic.rb
@@ -340,7 +340,7 @@ module Homebrew
         else
           inject_file_list @found, <<~EOS
             libiconv files detected at a system prefix other than /usr.
-            Homebrew doesn't provide a libiconv formula, and expects to link against
+            Homebrew doesn't provide a libiconv formula and expects to link against
             the system version in /usr. libiconv in other prefixes can cause
             compile or link failure, especially if compiled with improper
             architectures. macOS itself never installs anything to /usr/local so
diff --git a/Library/Homebrew/extend/os/mac/formula_cellar_checks.rb b/Library/Homebrew/extend/os/mac/formula_cellar_checks.rb
index e4ffde8f9f..e7188e670b 100644
--- a/Library/Homebrew/extend/os/mac/formula_cellar_checks.rb
+++ b/Library/Homebrew/extend/os/mac/formula_cellar_checks.rb
@@ -112,7 +112,7 @@ module FormulaCellarChecks
 
     <<~EOS
       Libraries were compiled with a flat namespace.
-      This can cause linker errors due to name collisions, and
+      This can cause linker errors due to name collisions and
       is often due to a bug in detecting the macOS version.
         #{flat_namespace_files * "\n  "}
     EOS
diff --git a/Library/Homebrew/fetch.rb b/Library/Homebrew/fetch.rb
index 587a17f4ed..9bbd8047e9 100644
--- a/Library/Homebrew/fetch.rb
+++ b/Library/Homebrew/fetch.rb
@@ -20,7 +20,7 @@ module Homebrew
       if os.present?
         return true
       elsif ENV["HOMEBREW_TEST_GENERIC_OS"].present?
-        # `:generic` bottles don't exist, and `--os` flag is not specified.
+        # `:generic` bottles don't exist and `--os` flag is not specified.
         return false
       end
       return true if arch.present?
diff --git a/Library/Homebrew/formula_assertions.rb b/Library/Homebrew/formula_assertions.rb
index ad9c7ebcc7..a7d6d0dd77 100644
--- a/Library/Homebrew/formula_assertions.rb
+++ b/Library/Homebrew/formula_assertions.rb
@@ -16,7 +16,8 @@ module Homebrew
       @assertions ||= 0
     end
 
-    # 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
@@ -28,8 +29,9 @@ module Homebrew
       raise
     end
 
-    # Returns the output of running the cmd with the optional input, and
+    # Returns the output of running the cmd with the optional input and
     # optionally asserts the exit status.
+    #
     # @api public
     def pipe_output(cmd, input = nil, result = nil)
       ohai cmd
diff --git a/Library/Homebrew/formula_creator.rb b/Library/Homebrew/formula_creator.rb
index da833cf4eb..8f362a82f9 100644
--- a/Library/Homebrew/formula_creator.rb
+++ b/Library/Homebrew/formula_creator.rb
@@ -99,6 +99,8 @@ module Homebrew
 
     sig { returns(String) }
     def template
+      # FIXME: https://github.com/errata-ai/vale/issues/818
+      # <!-- vale off -->
       <<~ERB
         # Documentation: https://docs.brew.sh/Formula-Cookbook
         #                https://rubydoc.brew.sh/Formula
@@ -183,14 +185,14 @@ module Homebrew
             ENV.prepend_create_path "PERL5LIB", libexec/"lib/perl5"
             ENV.prepend_path "PERL5LIB", libexec/"lib"
 
-            # Stage additional dependency (Makefile.PL style)
+            # Stage additional dependency (`Makefile.PL` style).
             # resource("").stage do
             #   system "perl", "Makefile.PL", "INSTALL_BASE=\#{libexec}"
             #   system "make"
             #   system "make", "install"
             # end
 
-            # Stage additional dependency (Build.PL style)
+            # Stage additional dependency (`Build.PL` style).
             # resource("").stage do
             #   system "perl", "Build.PL", "--install_base", libexec
             #   system "./Build"
@@ -231,6 +233,7 @@ module Homebrew
           end
         end
       ERB
+      # <!-- vale on -->
     end
   end
 end
diff --git a/Library/Homebrew/formulary.rb b/Library/Homebrew/formulary.rb
index dada7f3b0b..c479ddacdf 100644
--- a/Library/Homebrew/formulary.rb
+++ b/Library/Homebrew/formulary.rb
@@ -537,19 +537,19 @@ module Formulary
   class FormulaLoader
     include Context
 
-    # The formula's name
+    # The formula's name.
     sig { returns(String) }
     attr_reader :name
 
-    # The formula's ruby file's path or filename
+    # The formula file's path.
     sig { returns(Pathname) }
     attr_reader :path
 
-    # The name used to install the formula
+    # The name used to install the formula.
     sig { returns(T.nilable(Pathname)) }
     attr_reader :alias_path
 
-    # The formula's tap (nil if it should be implicitly determined)
+    # The formula's tap (`nil` if it should be implicitly determined).
     sig { returns(T.nilable(Tap)) }
     attr_reader :tap
 
@@ -1019,8 +1019,8 @@ module Formulary
   # 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
-  #   installed, and discarded if it is installed because the `alias_path` used
+  # @param alias_path will be used if the formula is found not to be
+  #   installed and discarded if it is installed because the `alias_path` used
   #   to install the formula will be set instead.
   sig {
     params(
diff --git a/Library/Homebrew/github_packages.rb b/Library/Homebrew/github_packages.rb
index 68f2f244ad..64aa192cc1 100644
--- a/Library/Homebrew/github_packages.rb
+++ b/Library/Homebrew/github_packages.rb
@@ -94,12 +94,12 @@ class GitHubPackages
   end
 
   def self.repo_without_prefix(repo)
-    # remove redundant repo prefix for a shorter name
+    # Remove redundant repository prefix for a shorter name.
     repo.delete_prefix("homebrew-")
   end
 
   def self.root_url(org, repo, prefix = URL_PREFIX)
-    # docker/skopeo insist on lowercase org ("repository name")
+    # `docker`/`skopeo` insist on lowercase organisation (“repository name”).
     org = org.downcase
 
     "#{prefix}#{org}/#{repo_without_prefix(repo)}"
@@ -115,9 +115,9 @@ class GitHubPackages
   end
 
   def self.image_formula_name(formula_name)
-    # invalid docker name characters
-    # / makes sense because we already use it to separate repo/formula
-    # x makes sense because we already use it in Formulary
+    # Invalid docker name characters:
+    # - `/` makes sense because we already use it to separate repository/formula.
+    # - `x` makes sense because we already use it in `Formulary`.
     formula_name.tr("@", "/")
                 .tr("+", "x")
   end
@@ -231,9 +231,9 @@ class GitHubPackages
       inspect_args << "--creds=#{user}:#{token}"
       inspect_result = system_command(skopeo, print_stderr: false, args: inspect_args)
 
-      # Order here is important
+      # Order here is important.
       if !inspect_result.status.success? && !inspect_result.stderr.match?(/(name|manifest) unknown/)
-        # We got an error, and it was not about the tag or package being unknown.
+        # We got an error and it was not about the tag or package being unknown.
         if warn_on_error
           opoo "#{image_uri} inspection returned an error, skipping upload!\n#{inspect_result.stderr}"
           return
@@ -241,11 +241,11 @@ class GitHubPackages
           odie "#{image_uri} inspection returned an error!\n#{inspect_result.stderr}"
         end
       elsif keep_old
-        # If the tag doesn't exist, ignore --keep-old.
+        # If the tag doesn't exist, ignore `--keep-old`.
         keep_old = false unless inspect_result.status.success?
         # Otherwise, do nothing - the tag already existing is expected behaviour for --keep-old.
       elsif inspect_result.status.success?
-        # The tag already exists, and we are not passing --keep-old.
+        # The tag already exists and we are not passing `--keep-old`.
         if warn_on_error
           opoo "#{image_uri} already exists, skipping upload!"
           return
diff --git a/Library/Homebrew/keg.rb b/Library/Homebrew/keg.rb
index d1ab5b375a..e418ce9d48 100644
--- a/Library/Homebrew/keg.rb
+++ b/Library/Homebrew/keg.rb
@@ -552,8 +552,8 @@ class Keg
 
     src = dst.resolved_path
 
-    # src itself may be a symlink, so check lstat to ensure we are dealing with
-    # a directory, and not a symlink pointing at a directory (which needs to be
+    # `src` itself may be a symlink, so check lstat to ensure we are dealing with
+    # a directory and not a symlink pointing to a directory (which needs to be
     # treated as a file). In other words, we only want to resolve one symlink.
 
     begin
diff --git a/Library/Homebrew/language/python.rb b/Library/Homebrew/language/python.rb
index 8aaa4c4c0b..a8006ac5ea 100644
--- a/Library/Homebrew/language/python.rb
+++ b/Library/Homebrew/language/python.rb
@@ -144,7 +144,7 @@ module Language
 
     # Mixin module for {Formula} adding virtualenv support features.
     module Virtualenv
-      # Instantiates, creates, and yields a {Virtualenv} object for use from
+      # 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.
       #
@@ -211,7 +211,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
+      # on the formula and then installs the formula. An options hash may be
       # 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
diff --git a/Library/Homebrew/livecheck/strategy/git.rb b/Library/Homebrew/livecheck/strategy/git.rb
index 7b5eeee405..ad9ce2526a 100644
--- a/Library/Homebrew/livecheck/strategy/git.rb
+++ b/Library/Homebrew/livecheck/strategy/git.rb
@@ -13,7 +13,7 @@ module Homebrew
       # 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
-      # `head`, `stable`, and then `homepage`. The higher priority here may
+      # `head`, `stable` and then `homepage`. The higher priority here may
       # be removed (or altered) in the future if we reevaluate this particular
       # behavior.
       #
diff --git a/Library/Homebrew/livecheck/strategy/json.rb b/Library/Homebrew/livecheck/strategy/json.rb
index b27e990bdf..ce0b8f5cc0 100644
--- a/Library/Homebrew/livecheck/strategy/json.rb
+++ b/Library/Homebrew/livecheck/strategy/json.rb
@@ -4,7 +4,7 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The {Json} strategy fetches content at a URL, parses it as JSON, and
+      # The {Json} strategy fetches content at a URL, parses it as JSON and
       # provides the parsed data to a `strategy` block. If a regex is present
       # in the `livecheck` block, it should be passed as the second argument to
       # the `strategy` block.
diff --git a/Library/Homebrew/livecheck/strategy/xml.rb b/Library/Homebrew/livecheck/strategy/xml.rb
index 26c2e874d3..362f373971 100644
--- a/Library/Homebrew/livecheck/strategy/xml.rb
+++ b/Library/Homebrew/livecheck/strategy/xml.rb
@@ -5,7 +5,7 @@ module Homebrew
   module Livecheck
     module Strategy
       # The {Xml} strategy fetches content at a URL, parses it as XML using
-      # `REXML`, and provides the `REXML::Document` to a `strategy` block.
+      # `REXML` and provides the `REXML::Document` to a `strategy` block.
       # If a regex is present in the `livecheck` block, it should be passed
       # as the second argument to the `strategy` block.
       #
diff --git a/Library/Homebrew/livecheck/strategy/yaml.rb b/Library/Homebrew/livecheck/strategy/yaml.rb
index 60e2290df3..407a8548b7 100644
--- a/Library/Homebrew/livecheck/strategy/yaml.rb
+++ b/Library/Homebrew/livecheck/strategy/yaml.rb
@@ -4,7 +4,7 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The {Yaml} strategy fetches content at a URL, parses it as YAML, and
+      # The {Yaml} strategy fetches content at a URL, parses it as YAML and
       # provides the parsed data to a `strategy` block. If a regex is present
       # in the `livecheck` block, it should be passed as the second argument to
       # the `strategy` block.
diff --git a/Library/Homebrew/manpages.rb b/Library/Homebrew/manpages.rb
index 1d5c3e40c3..6b90a1c186 100644
--- a/Library/Homebrew/manpages.rb
+++ b/Library/Homebrew/manpages.rb
@@ -142,7 +142,7 @@ module Homebrew
 
     sig { returns(String) }
     def self.global_cask_options_manpage
-      lines = ["These options are applicable to the `install`, `reinstall`, and `upgrade` " \
+      lines = ["These options are applicable to the `install`, `reinstall` and `upgrade` " \
                "subcommands with the `--cask` switch.\n"]
       lines += Homebrew::CLI::Parser.global_cask_options.map do |_, long, kwargs|
         generate_option_doc(nil, long.chomp("="), kwargs.fetch(:description))
diff --git a/Library/Homebrew/mktemp.rb b/Library/Homebrew/mktemp.rb
index 4bbf14b5dd..2d03ec6fca 100644
--- a/Library/Homebrew/mktemp.rb
+++ b/Library/Homebrew/mktemp.rb
@@ -1,7 +1,7 @@
 # typed: true
 # 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
diff --git a/Library/Homebrew/os/mac/sdk.rb b/Library/Homebrew/os/mac/sdk.rb
index 59471c744d..efea57282a 100644
--- a/Library/Homebrew/os/mac/sdk.rb
+++ b/Library/Homebrew/os/mac/sdk.rb
@@ -173,8 +173,8 @@ module OS
       # 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
-      # return nil SDKs for Xcode 9 and older.
+      # This will only look up SDKs on Xcode 10 or newer and still
+      # return `nil` SDKs for Xcode 9 and older.
       sig { override.returns(String) }
       def sdk_prefix
         @sdk_prefix ||= if CLT.provides_sdk?
diff --git a/Library/Homebrew/resource.rb b/Library/Homebrew/resource.rb
index 5f7cc32ad9..7a7517184e 100644
--- a/Library/Homebrew/resource.rb
+++ b/Library/Homebrew/resource.rb
@@ -170,8 +170,8 @@ class Resource < Downloadable
   end
 
   # Whether a livecheck specification is defined or not.
-  # It returns true when a livecheck block is present in the {Resource} and
-  # false otherwise, and is used by livecheck.
+  # It returns true when a `livecheck` block is present in the {Resource} and
+  # false otherwise and is used by livecheck.
   def livecheckable?
     @livecheckable == true
   end
diff --git a/Library/Homebrew/rubocops/cask/array_alphabetization.rb b/Library/Homebrew/rubocops/cask/array_alphabetization.rb
index 8e3e93b22d..ddbd872e4a 100644
--- a/Library/Homebrew/rubocops/cask/array_alphabetization.rb
+++ b/Library/Homebrew/rubocops/cask/array_alphabetization.rb
@@ -44,7 +44,7 @@ module RuboCop
           end
 
           # Separate the lines into those that should be sorted and those that should not
-          # ie. skip the opening and closing brackets of the array
+          # i.e. skip the opening and closing brackets of the array.
           to_sort, to_keep = combined_source.partition { |line| !line.include?("[") && !line.include?("]") }
 
           # Sort the lines that should be sorted
diff --git a/Library/Homebrew/rubocops/cask/url.rb b/Library/Homebrew/rubocops/cask/url.rb
index e659e9d92c..e8bc4f08c8 100644
--- a/Library/Homebrew/rubocops/cask/url.rb
+++ b/Library/Homebrew/rubocops/cask/url.rb
@@ -44,7 +44,7 @@ module RuboCop
 
             # Skip if the URL and the verified value are the same.
             next if value_node.source == url_stanza.source.gsub(%r{^"https?://}, "\"")
-            # Skip if the URL has two path components, eg: `https://github.com/google/fonts.git`.
+            # Skip if the URL has two path components, e.g. `https://github.com/google/fonts.git`.
             next if url_stanza.source.gsub(%r{^"https?://}, "\"").count("/") == 2
             # Skip if the verified value ends with a slash.
             next if value_node.str_content.end_with?("/")
diff --git a/Library/Homebrew/rubocops/compact_blank.rb b/Library/Homebrew/rubocops/compact_blank.rb
index 167465cfcb..9603abb675 100644
--- a/Library/Homebrew/rubocops/compact_blank.rb
+++ b/Library/Homebrew/rubocops/compact_blank.rb
@@ -13,7 +13,7 @@ module RuboCop
       #       `[[1, 2], [3, nil]].compact_blank` are not compatible. The same is true for `blank?`.
       #       This will work fine when the receiver is a hash object.
       #
-      #       And `compact_blank!` has different implementations for `Array`, `Hash`, and
+      #       And `compact_blank!` has different implementations for `Array`, `Hash` and
       #       `ActionController::Parameters`.
       #       `Array#compact_blank!`, `Hash#compact_blank!` are equivalent to `delete_if(&:blank?)`.
       #       `ActionController::Parameters#compact_blank!` is equivalent to `reject!(&:blank?)`.
diff --git a/Library/Homebrew/rubocops/homepage.rb b/Library/Homebrew/rubocops/homepage.rb
index e7e2b49c2a..c29ca23883 100644
--- a/Library/Homebrew/rubocops/homepage.rb
+++ b/Library/Homebrew/rubocops/homepage.rb
@@ -69,8 +69,8 @@ module RuboCop
           #
           # Compact the above into this list as we're able to remove detailed notations, etc over time.
           when
-               # Check for http:// GitHub homepage URLs, https:// is preferred.
-               # NOTE: Only check homepages that are repo pages, not *.github.com hosts.
+               # Check for `http://` GitHub homepage URLs, `https://` is preferred.
+               # NOTE: Only check homepages that are repository pages, not `*.github.com` hosts.
                %r{^http://github\.com/},
                %r{^http://[^/]*\.github\.io/},
 
diff --git a/Library/Homebrew/rubocops/urls.rb b/Library/Homebrew/rubocops/urls.rb
index c825d00398..f330387a41 100644
--- a/Library/Homebrew/rubocops/urls.rb
+++ b/Library/Homebrew/rubocops/urls.rb
@@ -127,7 +127,7 @@ module RuboCop
           # SourceForge url patterns
           sourceforge_patterns = %r{^https?://.*\b(sourceforge|sf)\.(com|net)}
           audit_urls(urls, sourceforge_patterns) do |_, url|
-            # Skip if the URL looks like a SVN repo
+            # Skip if the URL looks like a SVN repository.
             next if url.include? "/svnroot/"
             next if url.include? "svn.sourceforge"
             next if url.include? "/p/"
@@ -183,19 +183,19 @@ module RuboCop
             problem "Please use https:// for #{url}"
           end
 
-          # Check for git:// GitHub repo URLs, https:// is preferred.
+          # Check for `git://` GitHub repository 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 repository 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 repository URLs, https:// is preferred.
           gh_pattern = %r{^http://github\.com/.*\.git$}
           audit_urls(urls, gh_pattern) do |_, url|
             problem "Please use https:// for #{url}"
diff --git a/Library/Homebrew/software_spec.rb b/Library/Homebrew/software_spec.rb
index 3f3beb38a4..cc1d0a65d6 100644
--- a/Library/Homebrew/software_spec.rb
+++ b/Library/Homebrew/software_spec.rb
@@ -621,11 +621,11 @@ class BottleSpecification
   def checksums
     tags = collector.tags.sort_by do |tag|
       version = tag.to_macos_version
-      # Give arm64 bottles a higher priority so they are first
-      priority = (tag.arch == :arm64) ? "2" : "1"
+      # Give `arm64` bottles a higher priority so they are first.
+      priority = (tag.arch == :arm64) ? 2 : 1
       "#{priority}.#{version}_#{tag}"
     rescue MacOSVersion::Error
-      # Sort non-MacOS tags below MacOS tags.
+      # Sort non-macOS tags below macOS tags.
       "0.#{tag}"
     end
     tags.reverse.map do |tag|
diff --git a/Library/Homebrew/startup/config.rb b/Library/Homebrew/startup/config.rb
index 78161247f3..1251a8812a 100644
--- a/Library/Homebrew/startup/config.rb
+++ b/Library/Homebrew/startup/config.rb
@@ -12,7 +12,7 @@ HOMEBREW_PREFIX = Pathname(ENV.fetch("HOMEBREW_PREFIX")).freeze
 # Where `.git` is found
 HOMEBREW_REPOSITORY = Pathname(ENV.fetch("HOMEBREW_REPOSITORY")).freeze
 
-# Where we store most of Homebrew, taps, and various metadata
+# Where we store most of Homebrew, taps and various metadata
 HOMEBREW_LIBRARY = Pathname(ENV.fetch("HOMEBREW_LIBRARY")).freeze
 
 # Where shim scripts for various build and SCM tools are stored
@@ -39,7 +39,7 @@ HOMEBREW_CACHE = Pathname(ENV.fetch("HOMEBREW_CACHE")).freeze
 # Where formulae installed via URL are cached
 HOMEBREW_CACHE_FORMULA = (HOMEBREW_CACHE/"Formula").freeze
 
-# Where build, postinstall, and test logs of formulae are written to
+# Where build, postinstall and test logs of formulae are written to
 HOMEBREW_LOGS = Pathname(ENV.fetch("HOMEBREW_LOGS")).expand_path.freeze
 
 # Path to the list of Homebrew maintainers as a JSON file
diff --git a/Library/Homebrew/tap.rb b/Library/Homebrew/tap.rb
index 82d24e4d74..ab2046dae0 100644
--- a/Library/Homebrew/tap.rb
+++ b/Library/Homebrew/tap.rb
@@ -448,9 +448,9 @@ class Tap
     args << "--origin=origin"
     args << "-q" if quiet
 
-    # Override user-set default template
+    # Override user-set default template.
     args << "--template="
-    # prevent fsmonitor from watching this repo
+    # Prevent `fsmonitor` from watching this repository.
     args << "--config" << "core.fsmonitor=false"
 
     begin
diff --git a/Library/Homebrew/test/cask/artifact/abstract_artifact_spec.rb b/Library/Homebrew/test/cask/artifact/abstract_artifact_spec.rb
index 348011d80d..1bcde8ed7a 100644
--- a/Library/Homebrew/test/cask/artifact/abstract_artifact_spec.rb
+++ b/Library/Homebrew/test/cask/artifact/abstract_artifact_spec.rb
@@ -4,7 +4,7 @@ RSpec.describe Cask::Artifact::AbstractArtifact, :cask do
   describe ".read_script_arguments" do
     let(:stanza) { :installer }
 
-    it "accepts a string, and uses it as the executable" do
+    it "accepts a string and uses it as the executable" do
       arguments = "something"
 
       expect(described_class.read_script_arguments(arguments, stanza)).to eq(["something", {}])
diff --git a/Library/Homebrew/test/cask/dsl_spec.rb b/Library/Homebrew/test/cask/dsl_spec.rb
index 891c33a3a1..ab3131968e 100644
--- a/Library/Homebrew/test/cask/dsl_spec.rb
+++ b/Library/Homebrew/test/cask/dsl_spec.rb
@@ -5,7 +5,7 @@ RSpec.describe Cask::DSL, :cask do
   let(:token) { "basic-cask" }
 
   describe "stanzas" do
-    it "lets you set url, homepage, and version" do
+    it "lets you set url, homepage and version" do
       expect(cask.url.to_s).to eq("https://brew.sh/TestCask-1.2.3.dmg")
       expect(cask.homepage).to eq("https://brew.sh/")
       expect(cask.version.to_s).to eq("1.2.3")
diff --git a/Library/Homebrew/test/language/python/virtualenv_spec.rb b/Library/Homebrew/test/language/python/virtualenv_spec.rb
index bb03d7e498..27a9934f9f 100644
--- a/Library/Homebrew/test/language/python/virtualenv_spec.rb
+++ b/Library/Homebrew/test/language/python/virtualenv_spec.rb
@@ -140,7 +140,7 @@ RSpec.describe Language::Python::Virtualenv, :needs_python do
       end.to raise_error(ArgumentError)
     end
 
-    it "installs resources in correct order when combining `without`, `start_with`, and `end_with" do
+    it "installs resources in correct order when combining `without`, `start_with` and `end_with" do
       expect(f).to receive(:virtualenv_create).and_return(venv)
       expect(venv).to receive(:pip_install).with([r_d, r_c, r_b])
       expect(venv).to receive(:pip_install_and_link).with(buildpath, { link_manpages: false })
diff --git a/Library/Homebrew/test/livecheck/strategy/extract_plist_spec.rb b/Library/Homebrew/test/livecheck/strategy/extract_plist_spec.rb
index 8165439c4e..039cdc2507 100644
--- a/Library/Homebrew/test/livecheck/strategy/extract_plist_spec.rb
+++ b/Library/Homebrew/test/livecheck/strategy/extract_plist_spec.rb
@@ -72,7 +72,7 @@ RSpec.describe Homebrew::Livecheck::Strategy::ExtractPlist do
       ).to eq(versions)
     end
 
-    it "returns an array of version strings when given Items, a regex, and a block" do
+    it "returns an array of version strings when given `Item`s, a regex and a block" do
       # Returning a string from block
       expect(
         extract_plist.versions_from_items(multipart_items, multipart_regex) do |items, regex|
diff --git a/Library/Homebrew/test/livecheck/strategy/sparkle_spec.rb b/Library/Homebrew/test/livecheck/strategy/sparkle_spec.rb
index 97bc76ca69..c895fb53a7 100644
--- a/Library/Homebrew/test/livecheck/strategy/sparkle_spec.rb
+++ b/Library/Homebrew/test/livecheck/strategy/sparkle_spec.rb
@@ -395,7 +395,7 @@ RSpec.describe Homebrew::Livecheck::Strategy::Sparkle do
       ).to eq([items[:v121].nice_version])
     end
 
-    it "returns an array of version strings when given content, a regex, and a block" do
+    it "returns an array of version strings when given content, a regex and a block" do
       # Returning a string from the block
       expect(
         sparkle.versions_from_content(xml[:appcast], title_regex) do |item, regex|
diff --git a/Library/Homebrew/test/os/linux/dependency_collector_spec.rb b/Library/Homebrew/test/os/linux/dependency_collector_spec.rb
index 3ba82de27a..5df6690988 100644
--- a/Library/Homebrew/test/os/linux/dependency_collector_spec.rb
+++ b/Library/Homebrew/test/os/linux/dependency_collector_spec.rb
@@ -10,7 +10,7 @@ RSpec.describe DependencyCollector do
   describe "#add" do
     resource = Resource.new
 
-    context "when xz, unzip, and bzip2 are not available" do
+    context "when xz, unzip and bzip2 are not available" do
       it "creates a resource dependency from a '.xz' URL" do
         resource.url("https://brew.sh/foo.xz")
         allow_any_instance_of(Object).to receive(:which).with("xz")
@@ -30,7 +30,7 @@ RSpec.describe DependencyCollector do
       end
     end
 
-    context "when xz, zip, and bzip2 are available" do
+    context "when xz, zip and bzip2 are available" do
       it "does not create a resource dependency from a '.xz' URL" do
         resource.url("https://brew.sh/foo.xz")
         allow_any_instance_of(Object).to receive(:which).with("xz").and_return(Pathname.new("foo"))
diff --git a/Library/Homebrew/test/rubocops/caveats_spec.rb b/Library/Homebrew/test/rubocops/caveats_spec.rb
index 04cc4b35d6..93a80060be 100644
--- a/Library/Homebrew/test/rubocops/caveats_spec.rb
+++ b/Library/Homebrew/test/rubocops/caveats_spec.rb
@@ -13,7 +13,7 @@ RSpec.describe RuboCop::Cop::FormulaAudit::Caveats do
           url "https://brew.sh/foo-1.0.tgz"
            def caveats
             "setuid"
-            ^^^^^^^^ FormulaAudit/Caveats: Don't recommend setuid in the caveats, suggest sudo instead.
+            ^^^^^^^^ FormulaAudit/Caveats: Don't recommend `setuid` in the caveats, suggest `sudo` instead.
           end
         end
       RUBY
diff --git a/Library/Homebrew/test/spec_helper.rb b/Library/Homebrew/test/spec_helper.rb
index b525f7a11b..2dd6dc134d 100644
--- a/Library/Homebrew/test/spec_helper.rb
+++ b/Library/Homebrew/test/spec_helper.rb
@@ -102,7 +102,7 @@ RSpec.configure do |config|
   end
   config.mock_with :rspec do |mocks|
     # Prevents you from mocking or stubbing a method that does not exist on
-    # a real object. This is generally recommended, and will default to
+    # a real object. This is generally recommended and will default to
     # `true` in RSpec 4.
     mocks.verify_partial_doubles = true
   end
diff --git a/Library/Homebrew/test/utils/gzip_spec.rb b/Library/Homebrew/test/utils/gzip_spec.rb
index 4679a15e1e..bb16e3421d 100644
--- a/Library/Homebrew/test/utils/gzip_spec.rb
+++ b/Library/Homebrew/test/utils/gzip_spec.rb
@@ -6,7 +6,7 @@ RSpec.describe Utils::Gzip do
   include FileUtils
 
   describe "compress_with_options" do
-    it "uses the explicitly specified mtime, orig_name, and output path when passed" do
+    it "uses the explicitly specified mtime, orig_name and output path when passed" do
       mktmpdir do |path|
         mtime = Time.at(12345).utc
         orig_name = "someotherfile"
diff --git a/Library/Homebrew/test/utils/pypi_spec.rb b/Library/Homebrew/test/utils/pypi_spec.rb
index f5f529e143..e904988e2a 100644
--- a/Library/Homebrew/test/utils/pypi_spec.rb
+++ b/Library/Homebrew/test/utils/pypi_spec.rb
@@ -141,7 +141,7 @@ RSpec.describe PyPI do
         expect(package_with_version.pypi_info(new_version: "5.29.0")).to eq expected_result
       end
 
-      it "gets pypi info from a package name, extras, and version" do
+      it "gets pypi info from a package name, extras and version" do
         expected_result = ["snakemake", old_pypi_package_url, old_package_checksum, "5.28.0"]
         expect(package_with_extra_and_version.pypi_info).to eq expected_result
       end
diff --git a/Library/Homebrew/utils/curl.rb b/Library/Homebrew/utils/curl.rb
index 80cb908385..d23e0270e3 100644
--- a/Library/Homebrew/utils/curl.rb
+++ b/Library/Homebrew/utils/curl.rb
@@ -333,7 +333,7 @@ module Utils
         # GitHub does not authorize access to the web UI using token
         #
         # Strategy:
-        # If the `:homepage` 404s, it's a GitHub link, and we have a token then
+        # If the `:homepage` 404s, it's a GitHub link and we have a token then
         # check the API (which does use tokens) for the repository
         repo_details = url.match(%r{https?://github\.com/(?<user>[^/]+)/(?<repo>[^/]+)/?.*})
         check_github_api = url_type == SharedAudits::URL_TYPE_HOMEPAGE &&
@@ -483,7 +483,7 @@ module Utils
 
     # Separates the output text from `curl` into an array of HTTP responses and
     # the final response body (i.e. content). Response hashes contain the
-    # `:status_code`, `:status_text`, and `:headers`.
+    # `:status_code`, `:status_text` and `:headers`.
     # @param output [String] The output text from `curl` containing HTTP
     #   responses, body content, or both.
     # @param max_iterations [Integer] The maximum number of iterations for the
diff --git a/Library/Homebrew/utils/gems.rb b/Library/Homebrew/utils/gems.rb
index 756bb8808e..373f8a0958 100644
--- a/Library/Homebrew/utils/gems.rb
+++ b/Library/Homebrew/utils/gems.rb
@@ -231,7 +231,7 @@ module Homebrew
     invalid_groups = groups - valid_gem_groups
     raise ArgumentError, "Invalid gem groups: #{invalid_groups.join(", ")}" unless invalid_groups.empty?
 
-    # tests should not modify the state of the repo
+    # Tests should not modify the state of the repository.
     if ENV["HOMEBREW_TESTS"]
       setup_gem_environment!
       return
diff --git a/Library/Homebrew/utils/pypi.rb b/Library/Homebrew/utils/pypi.rb
index d6a6102bd8..db9f6337e7 100644
--- a/Library/Homebrew/utils/pypi.rb
+++ b/Library/Homebrew/utils/pypi.rb
@@ -49,7 +49,7 @@ module PyPI
       @is_pypi_url || !@is_url
     end
 
-    # Get name, URL, SHA-256 checksum, and latest version for a given package.
+    # Get name, URL, SHA-256 checksum and latest version for a given package.
     # This only works for packages from PyPI or from a PyPI URL; packages
     # derived from non-PyPI URLs will produce `nil` here.
     sig { params(new_version: T.nilable(T.any(String, Version))).returns(T.nilable(T::Array[String])) }
diff --git a/Library/Homebrew/utils/shell.rb b/Library/Homebrew/utils/shell.rb
index e7c3de4257..aee062fa90 100644
--- a/Library/Homebrew/utils/shell.rb
+++ b/Library/Homebrew/utils/shell.rb
@@ -110,26 +110,26 @@ module Utils
 
     sig { params(str: String).returns(String) }
     def csh_quote(str)
-      # ruby's implementation of shell_escape
+      # Ruby's implementation of `shell_escape`.
       str = str.to_s
       return "''" if str.empty?
 
       str = str.dup
-      # anything that isn't a known safe character is padded
+      # Anything that isn't a known safe character is padded.
       str.gsub!(UNSAFE_SHELL_CHAR, "\\\\" + "\\1") # rubocop:disable Style/StringConcatenation
-      # newlines have to be specially quoted in csh
+      # Newlines have to be specially quoted in `csh`.
       str.gsub!("\n", "'\\\n'")
       str
     end
 
     sig { params(str: String).returns(String) }
     def sh_quote(str)
-      # ruby's implementation of shell_escape
+      # Ruby's implementation of `shell_escape`.
       str = str.to_s
       return "''" if str.empty?
 
       str = str.dup
-      # anything that isn't a known safe character is padded
+      # Anything that isn't a known safe character is padded.
       str.gsub!(UNSAFE_SHELL_CHAR, "\\\\" + "\\1") # rubocop:disable Style/StringConcatenation
       str.gsub!("\n", "'\n'")
       str
diff --git a/Library/Homebrew/version.rb b/Library/Homebrew/version.rb
index e6e8dac8d0..274cd1aff2 100644
--- a/Library/Homebrew/version.rb
+++ b/Library/Homebrew/version.rb
@@ -382,115 +382,115 @@ class Version
 
   VERSION_PARSERS = [
     # date-based versioning
-    # e.g. 2023-09-28.tar.gz
-    # e.g. ltopers-v2017-04-14.tar.gz
+    # e.g. `2023-09-28.tar.gz`
+    # e.g. `ltopers-v2017-04-14.tar.gz`
     StemParser.new(/(?:^|[._-]?)v?(\d{4}-\d{2}-\d{2})/),
 
     # GitHub tarballs
-    # e.g. https://github.com/foo/bar/tarball/v1.2.3
-    # e.g. https://github.com/sam-github/libnet/tarball/libnet-1.1.4
-    # e.g. https://github.com/isaacs/npm/tarball/v0.2.5-1
-    # e.g. https://github.com/petdance/ack/tarball/1.93_02
+    # e.g. `https://github.com/foo/bar/tarball/v1.2.3`
+    # e.g. `https://github.com/sam-github/libnet/tarball/libnet-1.1.4`
+    # e.g. `https://github.com/isaacs/npm/tarball/v0.2.5-1`
+    # e.g. `https://github.com/petdance/ack/tarball/1.93_02`
     UrlParser.new(%r{github\.com/.+/(?:zip|tar)ball/(?:v|\w+-)?((?:\d+[._-])+\d*)$}),
 
-    # e.g. https://github.com/erlang/otp/tarball/OTP_R15B01 (erlang style)
+    # e.g. `https://github.com/erlang/otp/tarball/OTP_R15B01 (erlang style)`
     UrlParser.new(/[_-]([Rr]\d+[AaBb]\d*(?:-\d+)?)/),
 
-    # e.g. boost_1_39_0
+    # e.g. `boost_1_39_0`
     StemParser.new(/((?:\d+_)+\d+)$/) { |s| s.tr("_", ".") },
 
-    # e.g. foobar-4.5.1-1
-    # e.g. unrtf_0.20.4-1
-    # e.g. ruby-1.9.1-p243
+    # e.g. `foobar-4.5.1-1`
+    # e.g. `unrtf_0.20.4-1`
+    # e.g. `ruby-1.9.1-p243`
     StemParser.new(/[_-](#{NUMERIC_WITH_DOTS}-(?:p|P|rc|RC)?\d+)#{CONTENT_SUFFIX}?$/),
 
     # Hyphenated versions without software-name prefix (e.g. brew-)
-    # e.g. v0.0.8-12.tar.gz
-    # e.g. 3.3.04-1.tar.gz
-    # e.g. v2.1-20210510.tar.gz
-    # e.g. 2020.11.11-3.tar.gz
-    # e.g. v3.6.6-0.2
+    # e.g. `v0.0.8-12.tar.gz`
+    # e.g. `3.3.04-1.tar.gz`
+    # e.g. `v2.1-20210510.tar.gz`
+    # e.g. `2020.11.11-3.tar.gz`
+    # e.g. `v3.6.6-0.2`
     StemParser.new(/^v?(#{NUMERIC_WITH_DOTS}(?:-#{NUMERIC_WITH_OPTIONAL_DOTS})+)/),
 
     # URL with no extension
-    # e.g. https://waf.io/waf-1.8.12
-    # e.g. https://codeload.github.com/gsamokovarov/jump/tar.gz/v0.7.1
+    # e.g. `https://waf.io/waf-1.8.12`
+    # e.g. `https://codeload.github.com/gsamokovarov/jump/tar.gz/v0.7.1`
     UrlParser.new(/[-v](#{NUMERIC_WITH_OPTIONAL_DOTS})$/),
 
-    # e.g. lame-398-1
+    # e.g. `lame-398-1`
     StemParser.new(/-(\d+-\d+)/),
 
-    # e.g. foobar-4.5.1
+    # e.g. `foobar-4.5.1`
     StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS})$/),
 
-    # e.g. foobar-4.5.1.post1
+    # e.g. `foobar-4.5.1.post1`
     StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS}(.post\d+)?)$/),
 
-    # e.g. foobar-4.5.1b
+    # e.g. `foobar-4.5.1b`
     StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS}(?:[abc]|rc|RC)\d*)$/),
 
-    # e.g. foobar-4.5.0-alpha5, foobar-4.5.0-beta1, or foobar-4.50-beta
+    # e.g. `foobar-4.5.0-alpha5, foobar-4.5.0-beta1, or foobar-4.50-beta`
     StemParser.new(/-(#{NUMERIC_WITH_OPTIONAL_DOTS}-(?:alpha|beta|rc)\d*)$/),
 
-    # e.g. https://ftpmirror.gnu.org/libidn/libidn-1.29-win64.zip
-    # e.g. https://ftpmirror.gnu.org/libmicrohttpd/libmicrohttpd-0.9.17-w32.zip
+    # e.g. `https://ftpmirror.gnu.org/libidn/libidn-1.29-win64.zip`
+    # e.g. `https://ftpmirror.gnu.org/libmicrohttpd/libmicrohttpd-0.9.17-w32.zip`
     StemParser.new(/-(#{MINOR_OR_PATCH})-w(?:in)?(?:32|64)$/),
 
     # Opam packages
-    # e.g. https://opam.ocaml.org/archives/sha.1.9+opam.tar.gz
-    # e.g. https://opam.ocaml.org/archives/lablgtk.2.18.3+opam.tar.gz
-    # e.g. https://opam.ocaml.org/archives/easy-format.1.0.2+opam.tar.gz
+    # e.g. `https://opam.ocaml.org/archives/sha.1.9+opam.tar.gz`
+    # e.g. `https://opam.ocaml.org/archives/lablgtk.2.18.3+opam.tar.gz`
+    # e.g. `https://opam.ocaml.org/archives/easy-format.1.0.2+opam.tar.gz`
     StemParser.new(/\.(#{MINOR_OR_PATCH})\+opam$/),
 
-    # e.g. https://ftpmirror.gnu.org/mtools/mtools-4.0.18-1.i686.rpm
-    # e.g. https://ftpmirror.gnu.org/autogen/autogen-5.5.7-5.i386.rpm
-    # e.g. https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x86.zip
-    # e.g. https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x64.zip
-    # e.g. https://ftpmirror.gnu.org/mtools/mtools_4.0.18_i386.deb
+    # e.g. `https://ftpmirror.gnu.org/mtools/mtools-4.0.18-1.i686.rpm`
+    # e.g. `https://ftpmirror.gnu.org/autogen/autogen-5.5.7-5.i386.rpm`
+    # e.g. `https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x86.zip`
+    # e.g. `https://ftpmirror.gnu.org/libtasn1/libtasn1-2.8-x64.zip`
+    # e.g. `https://ftpmirror.gnu.org/mtools/mtools_4.0.18_i386.deb`
     StemParser.new(/[_-](#{MINOR_OR_PATCH}(?:-\d+)?)[._-](?:i[36]86|x86|x64(?:[_-](?:32|64))?)$/),
 
-    # e.g. https://registry.npmjs.org/@angular/cli/-/cli-1.3.0-beta.1.tgz
-    # e.g. https://github.com/dlang/dmd/archive/v2.074.0-beta1.tar.gz
-    # e.g. https://github.com/dlang/dmd/archive/v2.074.0-rc1.tar.gz
-    # e.g. https://github.com/premake/premake-core/releases/download/v5.0.0-alpha10/premake-5.0.0-alpha10-src.zip
+    # e.g. `https://registry.npmjs.org/@angular/cli/-/cli-1.3.0-beta.1.tgz`
+    # e.g. `https://github.com/dlang/dmd/archive/v2.074.0-beta1.tar.gz`
+    # e.g. `https://github.com/dlang/dmd/archive/v2.074.0-rc1.tar.gz`
+    # e.g. `https://github.com/premake/premake-core/releases/download/v5.0.0-alpha10/premake-5.0.0-alpha10-src.zip`
     StemParser.new(/[-.vV]?(#{NUMERIC_WITH_DOTS}#{PRERELEASE_SUFFIX})/),
 
-    # e.g. foobar4.5.1
+    # e.g. `foobar4.5.1`
     StemParser.new(/(#{NUMERIC_WITH_OPTIONAL_DOTS})$/),
 
-    # e.g. foobar-4.5.0-bin
+    # e.g. `foobar-4.5.0-bin`
     StemParser.new(/[-vV](#{NUMERIC_WITH_DOTS}[abc]?)#{CONTENT_SUFFIX}$/),
 
     # dash version style
-    # e.g. http://www.antlr.org/download/antlr-3.4-complete.jar
-    # e.g. https://cdn.nuxeo.com/nuxeo-9.2/nuxeo-server-9.2-tomcat.zip
-    # e.g. https://search.maven.org/remotecontent?filepath=com/facebook/presto/presto-cli/0.181/presto-cli-0.181-executable.jar
-    # e.g. https://search.maven.org/remotecontent?filepath=org/fusesource/fuse-extra/fusemq-apollo-mqtt/1.3/fusemq-apollo-mqtt-1.3-uber.jar
-    # e.g. https://search.maven.org/remotecontent?filepath=org/apache/orc/orc-tools/1.2.3/orc-tools-1.2.3-uber.jar
+    # e.g. `http://www.antlr.org/download/antlr-3.4-complete.jar`
+    # e.g. `https://cdn.nuxeo.com/nuxeo-9.2/nuxeo-server-9.2-tomcat.zip`
+    # e.g. `https://search.maven.org/remotecontent?filepath=com/facebook/presto/presto-cli/0.181/presto-cli-0.181-executable.jar`
+    # e.g. `https://search.maven.org/remotecontent?filepath=org/fusesource/fuse-extra/fusemq-apollo-mqtt/1.3/fusemq-apollo-mqtt-1.3-uber.jar`
+    # e.g. `https://search.maven.org/remotecontent?filepath=org/apache/orc/orc-tools/1.2.3/orc-tools-1.2.3-uber.jar`
     StemParser.new(/-(#{NUMERIC_WITH_DOTS})-/),
 
-    # e.g. dash_0.5.5.1.orig.tar.gz (Debian style)
+    # e.g. `dash_0.5.5.1.orig.tar.gz (Debian style)`
     StemParser.new(/_(#{NUMERIC_WITH_DOTS}[abc]?)\.orig$/),
 
-    # e.g. https://www.openssl.org/source/openssl-0.9.8s.tar.gz
+    # e.g. `https://www.openssl.org/source/openssl-0.9.8s.tar.gz`
     StemParser.new(/-v?(\d[^-]+)/),
 
-    # e.g. astyle_1.23_macosx.tar.gz
+    # e.g. `astyle_1.23_macosx.tar.gz`
     StemParser.new(/_v?(\d[^_]+)/),
 
-    # e.g. http://mirrors.jenkins-ci.org/war/1.486/jenkins.war
-    # e.g. https://github.com/foo/bar/releases/download/0.10.11/bar.phar
-    # e.g. https://github.com/clojure/clojurescript/releases/download/r1.9.293/cljs.jar
-    # e.g. https://github.com/fibjs/fibjs/releases/download/v0.6.1/fullsrc.zip
-    # e.g. https://wwwlehre.dhbw-stuttgart.de/~sschulz/WORK/E_DOWNLOAD/V_1.9/E.tgz
-    # e.g. https://github.com/JustArchi/ArchiSteamFarm/releases/download/2.3.2.0/ASF.zip
-    # e.g. https://people.gnome.org/~newren/eg/download/1.7.5.2/eg
+    # e.g. `http://mirrors.jenkins-ci.org/war/1.486/jenkins.war`
+    # e.g. `https://github.com/foo/bar/releases/download/0.10.11/bar.phar`
+    # e.g. `https://github.com/clojure/clojurescript/releases/download/r1.9.293/cljs.jar`
+    # e.g. `https://github.com/fibjs/fibjs/releases/download/v0.6.1/fullsrc.zip`
+    # e.g. `https://wwwlehre.dhbw-stuttgart.de/~sschulz/WORK/E_DOWNLOAD/V_1.9/E.tgz`
+    # e.g. `https://github.com/JustArchi/ArchiSteamFarm/releases/download/2.3.2.0/ASF.zip`
+    # e.g. `https://people.gnome.org/~newren/eg/download/1.7.5.2/eg`
     UrlParser.new(%r{/(?:[rvV]_?)?(\d+\.\d+(?:\.\d+){,2})}),
 
-    # e.g. https://www.ijg.org/files/jpegsrc.v8d.tar.gz
+    # e.g. `https://www.ijg.org/files/jpegsrc.v8d.tar.gz`
     StemParser.new(/\.v(\d+[a-z]?)/),
 
-    # e.g. https://secure.php.net/get/php-7.1.10.tar.bz2/from/this/mirror
+    # e.g. `https://secure.php.net/get/php-7.1.10.tar.bz2/from/this/mirror`
     UrlParser.new(/[-.vV]?(#{NUMERIC_WITH_DOTS}#{PRERELEASE_SUFFIX}?)/),
   ].freeze
   private_constant :VERSION_PARSERS
diff --git a/Library/Homebrew/warnings.rb b/Library/Homebrew/warnings.rb
index 94f0629290..83c124234a 100644
--- a/Library/Homebrew/warnings.rb
+++ b/Library/Homebrew/warnings.rb
@@ -9,7 +9,10 @@ module Warnings
     parser_syntax: [
       %r{warning: parser/current is loading parser/ruby\d+, which recognizes},
       /warning: \d+\.\d+\.\d+-compliant syntax, but you are running \d+\.\d+\.\d+\./,
+      # FIXME: https://github.com/errata-ai/vale/issues/818
+      # <!-- vale off -->
       %r{warning: please see https://github\.com/whitequark/parser#compatibility-with-ruby-mri\.},
+      # <!-- vale on -->
     ],
   }.freeze
 
diff --git a/completions/fish/brew.fish b/completions/fish/brew.fish
index cfd60856b8..96c071b87a 100644
--- a/completions/fish/brew.fish
+++ b/completions/fish/brew.fish
@@ -1196,7 +1196,7 @@ __fish_brew_complete_arg 'pr-publish' -l verbose -d 'Make some output more verbo
 __fish_brew_complete_arg 'pr-publish' -l workflow -d 'Target workflow filename (default: `publish-commit-bottles.yml`)'
 
 
-__fish_brew_complete_cmd 'pr-pull' 'Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions'
+__fish_brew_complete_cmd 'pr-pull' 'Download and publish bottles and apply the bottle commit from a pull request with artifacts generated by GitHub Actions'
 __fish_brew_complete_arg 'pr-pull' -l artifact-pattern -d 'Download artifacts with the specified pattern (default: `bottles{,_*}`)'
 __fish_brew_complete_arg 'pr-pull' -l autosquash -d 'Automatically reformat and reword commits in the pull request to our preferred format'
 __fish_brew_complete_arg 'pr-pull' -l branch-okay -d 'Do not warn if pulling to a branch besides the repository default (useful for testing)'
@@ -1482,12 +1482,12 @@ __fish_brew_complete_arg 'test' -a '(__fish_brew_suggest_formulae_installed)'
 __fish_brew_complete_cmd 'tests' 'Run Homebrew\'s unit and integration tests'
 __fish_brew_complete_arg 'tests' -l changed -d 'Only runs tests on files that were changed from the master branch'
 __fish_brew_complete_arg 'tests' -l coverage -d 'Generate code coverage reports'
-__fish_brew_complete_arg 'tests' -l debug -d 'Enable debugging using ruby/debug, or surface the standard `odebug` output'
+__fish_brew_complete_arg 'tests' -l debug -d 'Enable debugging using `ruby/debug`, or surface the standard `odebug` output'
 __fish_brew_complete_arg 'tests' -l fail-fast -d 'Exit early on the first failing test'
 __fish_brew_complete_arg 'tests' -l generic -d 'Run only OS-agnostic tests'
 __fish_brew_complete_arg 'tests' -l help -d 'Show this message'
 __fish_brew_complete_arg 'tests' -l online -d 'Include tests that use the GitHub API and tests that use any of the taps for official external commands'
-__fish_brew_complete_arg 'tests' -l only -d 'Run only test_script`_spec.rb`. Appending `:`line_number will start at a specific line'
+__fish_brew_complete_arg 'tests' -l only -d 'Run only `test_script_spec.rb`. Appending `:line_number` will start at a specific line'
 __fish_brew_complete_arg 'tests' -l profile -d 'Run the test suite serially to find the n slowest tests'
 __fish_brew_complete_arg 'tests' -l quiet -d 'Make some output more quiet'
 __fish_brew_complete_arg 'tests' -l seed -d 'Randomise tests with the specified value instead of a random seed'
diff --git a/completions/zsh/_brew b/completions/zsh/_brew
index 6a4fe95e06..3d85195e6e 100644
--- a/completions/zsh/_brew
+++ b/completions/zsh/_brew
@@ -195,7 +195,7 @@ __brew_internal_commands() {
     'postinstall:Rerun the post-install steps for formula'
     'pr-automerge:Find pull requests that can be automatically merged using `brew pr-publish`'
     'pr-publish:Publish bottles for a pull request with GitHub Actions'
-    'pr-pull:Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions'
+    'pr-pull:Download and publish bottles and apply the bottle commit from a pull request with artifacts generated by GitHub Actions'
     'pr-upload:Apply the bottle commit and publish bottles to a host'
     'prof:Run Homebrew with a Ruby profiler'
     'pyenv-sync:Create symlinks for Homebrew'\''s installed Python versions in `~/.pyenv/versions`'
@@ -1835,12 +1835,12 @@ _brew_tests() {
   _arguments \
     '(--only)--changed[Only runs tests on files that were changed from the master branch]' \
     '--coverage[Generate code coverage reports]' \
-    '--debug[Enable debugging using ruby/debug, or surface the standard `odebug` output]' \
+    '--debug[Enable debugging using `ruby/debug`, or surface the standard `odebug` output]' \
     '--fail-fast[Exit early on the first failing test]' \
     '--generic[Run only OS-agnostic tests]' \
     '--help[Show this message]' \
     '--online[Include tests that use the GitHub API and tests that use any of the taps for official external commands]' \
-    '(--changed)--only[Run only test_script`_spec.rb`. Appending `:`line_number will start at a specific line]' \
+    '(--changed)--only[Run only `test_script_spec.rb`. Appending `:line_number` will start at a specific line]' \
     '--profile[Run the test suite serially to find the n slowest tests]' \
     '--quiet[Make some output more quiet]' \
     '--seed[Randomise tests with the specified value instead of a random seed]' \
diff --git a/docs/External-Commands.md b/docs/External-Commands.md
index 8c58a0f4c4..ec5f5f4c84 100644
--- a/docs/External-Commands.md
+++ b/docs/External-Commands.md
@@ -24,7 +24,7 @@ The command may `Kernel.exit` with a status code if it needs to; if it doesn't e
 
 ### Other executable scripts
 
-An executable script for a command named `extcmd` should be named `brew-extcmd`. The script itself can use any suitable shebang (`#!`) line, so an external script can be written in Bash, Ruby, or even Python. Unlike the ruby commands this file must not end with a language-specific suffix (`.sh`, or `.py`). This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments.
+An executable script for a command named `extcmd` should be named `brew-extcmd`. The script itself can use any suitable shebang (`#!`) line, so an external script can be written in Bash, Ruby, or even Python. Unlike the Ruby commands this file must not end with a language-specific suffix (`.sh`, or `.py`). This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments.
 
 | variable               | description |
 | ---------------------- | ----------- |
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index 71cc55435e..600be521e1 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -1175,7 +1175,7 @@ brew search --fink foo
 
 `superenv` is our "super environment" that isolates builds by removing `/usr/local/bin` and all user `PATH`s that are not essential for the build. It does this because user `PATH`s are often full of stuff that breaks builds. `superenv` also removes bad flags from the commands passed to `clang`/`gcc` and injects others (for example all [`keg_only`](https://rubydoc.brew.sh/Formula#keg_only-class_method) dependencies are added to the `-I` and `-L` flags).
 
-If in your local Homebrew build of your new formula, you see `Operation not permitted` errors, this will be because your new formula tried to write to the disk outside of your sandbox area. This is enforced on MacOS by `sandbox-exec`.
+If in your local Homebrew build of your new formula, you see `Operation not permitted` errors, this will be because your new formula tried to write to the disk outside of your sandbox area. This is enforced on macOS by `sandbox-exec`.
 
 ### Fortran
 
diff --git a/docs/How-To-Organize-AGM.md b/docs/How-To-Organize-AGM.md
index 42b515c570..160686964e 100644
--- a/docs/How-To-Organize-AGM.md
+++ b/docs/How-To-Organize-AGM.md
@@ -87,7 +87,7 @@ using this quick command:_
 
 **When:** Week 1 of YEAR :date: `2024-01-01`
 
-* [ ] PLC: Solicit changes to [Homebrew Governance](Homebrew-Governance.md) in the form of PRs on the `homebrew-governance-private` repo.
+* [ ] PLC: Solicit changes to [Homebrew Governance](Homebrew-Governance.md) in the form of PRs on the `homebrew-governance-private` repository.
 
 ### Three weeks prior
 
diff --git a/docs/Manpage.md b/docs/Manpage.md
index f109d95270..8cd17e80dc 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -879,7 +879,7 @@ Show install options specific to *`formula`*.
 ### `outdated` \[*`options`*\] \[*`formula`*\|*`cask`* ...\]
 
 List installed casks and formulae that have an updated version available. By
-default, version information is displayed in interactive shells, and suppressed
+default, version information is displayed in interactive shells and suppressed
 otherwise.
 
 `-q`, `--quiet`
@@ -2379,7 +2379,7 @@ the repository.
 
 ### `pr-pull` \[*`options`*\] *`pull_request`* \[...\]
 
-Download and publish bottles, and apply the bottle commit from a pull request
+Download and publish bottles and apply the bottle commit from a pull request
 with artifacts generated by GitHub Actions. Requires write access to the
 repository.
 
@@ -2681,7 +2681,7 @@ Run Homebrew's unit and integration tests.
 
 `--debug`
 
-: Enable debugging using ruby/debug, or surface the standard `odebug` output.
+: Enable debugging using `ruby/debug`, or surface the standard `odebug` output.
 
 `--changed`
 
@@ -2693,8 +2693,8 @@ Run Homebrew's unit and integration tests.
 
 `--only`
 
-: Run only *`test_script`*`_spec.rb`. Appending `:`*`line_number`* will start at
-  a specific line.
+: Run only `<test_script>_spec.rb`. Appending `:<line_number>` will start at a
+  specific line.
 
 `--profile`
 
@@ -2874,7 +2874,7 @@ Install and commit Homebrew's vendored gems.
 
 ## GLOBAL CASK OPTIONS
 
-These options are applicable to the `install`, `reinstall`, and `upgrade`
+These options are applicable to the `install`, `reinstall` and `upgrade`
 subcommands with the `--cask` switch.
 
 `--appdir`
diff --git a/docs/Taps.md b/docs/Taps.md
index 74d2637b7f..c56363932f 100644
--- a/docs/Taps.md
+++ b/docs/Taps.md
@@ -16,23 +16,18 @@ but the command isn't limited to any one location.
   petere/postgresql
   ```
 
-<!-- vale Homebrew.Terms = OFF -->
-<!-- The `terms` lint suggests changing "repo" to "repository". But we need the abbreviation in the tap syntax and URL example. -->
-
-* `brew tap <user/repo>` makes a clone of the repository at
-  _https://github.com/\<user>/homebrew-\<repo>_ into `$(brew --repository)/Library/Taps`.
+* `brew tap <user>/<repo>` makes a clone of the repository at
+  `https://github.com/<user>/homebrew-<repo>` into `$(brew --repository)/Library/Taps`.
   After that, `brew` will be able to work with those formulae as if they were in Homebrew's
   [homebrew/core](https://github.com/Homebrew/homebrew-core) canonical repository.
   You can install and uninstall them with `brew [un]install`, and the formulae are
   automatically updated when you run `brew update`. (See below for details
   about how `brew tap` handles the names of repositories.)
 
-<!-- vale Homebrew.Terms = ON -->
-
-* `brew tap <user/repo> <URL>` makes a clone of the repository at _URL_.
+* `brew tap <user>/<repo> <URL>` makes a clone of the repository at _URL_.
   Unlike the one-argument version, _URL_ is not assumed to be GitHub, and it
   doesn't have to be HTTP. Any location and any protocol that Git can handle is
-  fine, although non-GitHub taps require running `brew tap --force-auto-update <user/repo>`
+  fine, although non-GitHub taps require running `brew tap --force-auto-update <user>/<repo>`
   to enable automatic updating.
 
 * `brew tap --repair` migrates tapped formulae from a symlink-based to
diff --git a/docs/governance/2021-agm-minutes.md b/docs/governance/2021-agm-minutes.md
index 8e3ea8b38e..65f4c9e698 100644
--- a/docs/governance/2021-agm-minutes.md
+++ b/docs/governance/2021-agm-minutes.md
@@ -45,7 +45,7 @@
 - 12:40–12:45 Michka Popoff - Merging the cores <https://github.com/Homebrew/brew/issues/7028>
 - 12:45–12:50 Michka Popoff - Linux CI for homebrew-core <https://github.com/Homebrew/brew/issues/10597>
 - 12:50–13:55 Misty De Meo - Running Homebrew on Apple Silicon
-- 12:55–13:00 Shaun Jackman - Speeding up install times / Git repo size <https://github.com/Homebrew/install/issues/523>
+- 12:55–13:00 Shaun Jackman - Speeding up install times/Git repository size <https://github.com/Homebrew/install/issues/523>
 - 13:10 Meeting adjourned
 
 ## Resolutions
diff --git a/docs/vale-styles/Homebrew/Abbreviations.yml b/docs/vale-styles/Homebrew/Abbreviations.yml
index df562c44aa..f51c2dd53f 100644
--- a/docs/vale-styles/Homebrew/Abbreviations.yml
+++ b/docs/vale-styles/Homebrew/Abbreviations.yml
@@ -1,6 +1,6 @@
 ---
 extends: substitution
-message: Use '%s'
+message: Use '%s' instead of '%s'.
 ignorecase: false
 link: "https://github.com/Homebrew/brew/blob/HEAD/docs/Prose-Style-Guidelines.md#style-and-usage"
 level: error
@@ -10,3 +10,9 @@ swap:
   '\bie\b': i.e.
   'e\.g\.,': e.g.
   'i\.e\.,': i.e.
+  '(?<!^\{.*|\.|<)\borg\b': organisation
+  '(?<!^\{.*)\borgs\b': organisations
+  '(?<!^\{.*|<|\{#)\brepo\b': repository # FIXME: https://github.com/errata-ai/vale/issues/818
+  '(?<!^\{.*)\brepos\b': repositories
+  '\bivar\b': instance variable
+  '\bivars\b': instance variables
diff --git a/docs/vale-styles/Homebrew/Spacing.yml b/docs/vale-styles/Homebrew/Spacing.yml
index ca752c5db3..5ab71b63b6 100644
--- a/docs/vale-styles/Homebrew/Spacing.yml
+++ b/docs/vale-styles/Homebrew/Spacing.yml
@@ -5,5 +5,5 @@ link: "https://github.com/Homebrew/brew/blob/HEAD/docs/Prose-Style-Guidelines.md
 level: error
 nonword: true
 tokens:
-  - "[a-z][.?!][A-Z]"
-  - "[.?!] {2,}[A-Z]"
+  - '(?<!^\{.*)[a-z][.?!][A-Z]' # FIXME: https://github.com/errata-ai/vale/issues/818
+  - '[.?!] {2,}[A-Z]'
diff --git a/docs/vale-styles/Homebrew/Terms.yml b/docs/vale-styles/Homebrew/Terms.yml
index 915388cd2a..82c6ca07c7 100644
--- a/docs/vale-styles/Homebrew/Terms.yml
+++ b/docs/vale-styles/Homebrew/Terms.yml
@@ -6,7 +6,7 @@ level: error
 scope: paragraph
 
 swap:
-  "(?<!How to Open a Homebrew )Pull Request": pull request
-  repo: repository
-  repos: repositories
+  '(?<!How to Open a Homebrew )Pull Request': pull request
   Rubocop: RuboCop
+  '(?<!^\{.*)MacOS': macOS # FIXME: https://github.com/errata-ai/vale/issues/818
+  '(?<!^\{.*|^!/.*)ruby': Ruby # FIXME: https://github.com/errata-ai/vale/issues/818
diff --git a/manpages/README.md b/manpages/README.md
index 40f8150788..5970ecf3ce 100644
--- a/manpages/README.md
+++ b/manpages/README.md
@@ -1,3 +1,3 @@
-# Manual pages
+# Manual Pages
 
 This directory contains the generated Homebrew man pages from the `brew generate-man-completions` command. This command creates the output from the `CLI::Parser` definitions in files, sections extracted from the repository's `README.md` and `brew.1.md.erb`.
diff --git a/manpages/brew.1 b/manpages/brew.1
index c6480a9e9a..68ecb4ae1d 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -550,7 +550,7 @@ Evaluate all available formulae and casks, whether installed or not, to show the
 \fB\-\-command\fP
 Show options for the specified \fIcommand\fP\&\.
 .SS "\fBoutdated\fP \fR[\fIoptions\fP] \fR[\fIformula\fP|\fIcask\fP \.\.\.]"
-List installed casks and formulae that have an updated version available\. By default, version information is displayed in interactive shells, and suppressed otherwise\.
+List installed casks and formulae that have an updated version available\. By default, version information is displayed in interactive shells and suppressed otherwise\.
 .TP
 \fB\-q\fP, \fB\-\-quiet\fP
 List only the names of outdated kegs (takes precedence over \fB\-\-verbose\fP)\.
@@ -1514,7 +1514,7 @@ Target tap repository (default: \fBhomebrew/core\fP)\.
 \fB\-\-workflow\fP
 Target workflow filename (default: \fBpublish\-commit\-bottles\.yml\fP)\.
 .SS "\fBpr\-pull\fP \fR[\fIoptions\fP] \fIpull_request\fP \fR[\.\.\.]"
-Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions\. Requires write access to the repository\.
+Download and publish bottles and apply the bottle commit from a pull request with artifacts generated by GitHub Actions\. Requires write access to the repository\.
 .TP
 \fB\-\-no\-upload\fP
 Download the bottles but don\[u2019]t upload them\.
@@ -1708,7 +1708,7 @@ Run only OS\-agnostic tests\.
 Include tests that use the GitHub API and tests that use any of the taps for official external commands\.
 .TP
 \fB\-\-debug\fP
-Enable debugging using ruby/debug, or surface the standard \fBodebug\fP output\.
+Enable debugging using \fBruby/debug\fP, or surface the standard \fBodebug\fP output\.
 .TP
 \fB\-\-changed\fP
 Only runs tests on files that were changed from the master branch\.
@@ -1717,7 +1717,7 @@ Only runs tests on files that were changed from the master branch\.
 Exit early on the first failing test\.
 .TP
 \fB\-\-only\fP
-Run only \fItest_script\fP\fB_spec\.rb\fP\&\. Appending \fB:\fP\fIline_number\fP will start at a specific line\.
+Run only \fB<test_script>_spec\.rb\fP\&\. Appending \fB:<line_number>\fP will start at a specific line\.
 .TP
 \fB\-\-profile\fP
 Run the test suite serially to find the \fIn\fP slowest tests\.
@@ -1836,7 +1836,7 @@ Update the specified list of vendored gems to the latest version\.
 \fB\-\-no\-commit\fP
 Do not generate a new commit upon completion\.
 .SH "GLOBAL CASK OPTIONS"
-These options are applicable to the \fBinstall\fP, \fBreinstall\fP, and \fBupgrade\fP subcommands with the \fB\-\-cask\fP switch\.
+These options are applicable to the \fBinstall\fP, \fBreinstall\fP and \fBupgrade\fP subcommands with the \fB\-\-cask\fP switch\.
 .TP
 \fB\-\-appdir\fP
 Target location for Applications (default: \fB/Applications\fP)\.