Lint Ruby docs.

Author: reitermarkus

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

.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

.vale.ini

@@ -1,4 +1,7 @@
 StylesPath = ./docs/vale-styles
 
-[*.md]
+[formats]
+rb = md
+
+[*.{md,rb}]
 BasedOnStyles = Homebrew

Library/Homebrew/abstract_command.rb

@@ -6,9 +6,10 @@
 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.

Library/Homebrew/build_environment.rb

@@ -28,7 +28,7 @@ def std?
   # 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

Library/Homebrew/cask/audit.rb

@@ -685,7 +685,7 @@ def audit_gitlab_prerelease_version
 
     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 @@ def audit_github_repository_archived
 
     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?

Library/Homebrew/cleaner.rb

@@ -25,27 +25,28 @@ def initialize(formula)
   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 @@ def executable_path?(path)
   # 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 @@ def clean_dir(directory)
       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

Library/Homebrew/cleanup.rb

@@ -376,7 +376,7 @@ def cleanup_logs
     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 @@ def cleanup_python_site_packages
       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")
 

Library/Homebrew/cmd/--prefix.rb

@@ -95,7 +95,7 @@ def list_unbrewed
         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

Library/Homebrew/cmd/outdated.rb

@@ -13,7 +13,7 @@ class Outdated < AbstractCommand
       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`)."

Library/Homebrew/dependencies_helpers.rb

@@ -33,7 +33,7 @@ def recursive_includes(klass, root_dependent, includes, ignores)
       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

Library/Homebrew/dependency_collector.rb

@@ -7,13 +7,13 @@
 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.

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

@@ -15,7 +15,7 @@ class PrPull < AbstractCommand
 
       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 @@ def run
         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 @@ def squash_package_commits(commits, file, git_repo:, reason: "", verbose: false,
         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)

Library/Homebrew/dev-cmd/tap-new.rb

@@ -46,6 +46,8 @@ def run
 
         (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 @@ def run
 
           `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

Library/Homebrew/dev-cmd/tests.rb

@@ -22,13 +22,13 @@ class Tests < AbstractCommand
                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 @@ def run
           end
 
           # Workaround for:
+          #
+          # ```
           # ruby: no -r allowed while running setuid (SecurityError)
+          # ```
           Process::UID.change_privilege(Process.euid) if Process.euid != Process.uid
 
           if parallel

Library/Homebrew/dev-cmd/update-test.rb

@@ -116,7 +116,7 @@ def run
           # 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

Library/Homebrew/diagnostic.rb

@@ -221,7 +221,7 @@ def check_for_stray_dylibs
         __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 @@ def check_for_stray_static_libs
         __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 @@ def check_for_stray_pcs
         __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 @@ def check_for_stray_las
         __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 @@ def check_for_stray_headers
         __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 @@ def check_for_git
 
         <<~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

Library/Homebrew/download_strategy.rb

@@ -931,8 +931,8 @@ def clone_args
 
     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
 

Library/Homebrew/extend/ENV.rb

@@ -17,10 +17,16 @@ def superenv?(env)
   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)

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 Install
     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[