vale

Library/Homebrew/extend/enumerable.rb

@@ -2,29 +2,37 @@
 # frozen_string_literal: true
 
 module Enumerable
-  # The negative of the <tt>Enumerable#include?</tt>. Returns +true+ if the
+  # The negative of the {Enumerable#include?}. Returns `true` if the
   # collection does not include the object.
   sig { params(object: T.untyped).returns(T::Boolean) }
   def exclude?(object) = !include?(object)
 
   # Returns a new +Array+ without the blank items.
   # Uses Object#blank? for determining if an item is blank.
   #
-  #   [1, "", nil, 2, " ", [], {}, false, true].compact_blank
-  #   # =>  [1, 2, true]
+  # ### Examples
   #
-  #   Set.new([nil, "", 1, false]).compact_blank
-  #   # => [1]
+  # ```
+  # [1, "", nil, 2, " ", [], {}, false, true].compact_blank
+  # # =>  [1, 2, true]
+  # ```
   #
-  # When called on a +Hash+, returns a new +Hash+ without the blank values.
+  # ```ruby
+  # Set.new([nil, "", 1, false]).compact_blank
+  # # => [1]
+  # ```
   #
-  #   { a: "", b: 1, c: nil, d: [], e: false, f: true }.compact_blank
-  #   # => { b: 1, f: true }
+  # When called on a {Hash}, returns a new {Hash} without the blank values.
+  #
+  # ```ruby
+  # { a: "", b: 1, c: nil, d: [], e: false, f: true }.compact_blank
+  # # => { b: 1, f: true }
+  # ```
   sig { returns(T.self_type) }
   def compact_blank = T.unsafe(self).reject(&:blank?)
 end
 
 class Hash
-  # Hash#reject has its own definition, so this needs one too.
+  # {Hash#reject} has its own definition, so this needs one too.
   def compact_blank = reject { |_k, v| T.unsafe(v).blank? }
 end

Library/Homebrew/github_packages.rb

@@ -99,7 +99,7 @@ def self.repo_without_prefix(repo)
   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 @@ def self.root_url_if_match(url)
   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

docs/vale-styles/Homebrew/Abbreviations.yml

@@ -10,6 +10,7 @@ swap:
   '\bie\b': i.e.
   'e\.g\.,': e.g.
   'i\.e\.,': i.e.
+  org: organisation
   repo: repository
   repos: repositories
   ivar: instance variable