apidoc: update comment wording, punctuation, formatting

Library/Homebrew/rubocops/class.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop makes sure that `Formula` is used as superclass.
+      # This cop makes sure that {Formula} is used as superclass.
       #
       # @api private
       class ClassName < FormulaCop

Library/Homebrew/rubocops/components_order.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop checks for correct order of components in Formulae.
+      # This cop checks for correct order of components in formulae.
       #
       # - `component_precedence_list` has component hierarchy in a nested list
       #   where each sub array contains components' details which are at same precedence level
@@ -157,7 +157,7 @@ module RuboCop
           end
         end
 
-        # autocorrect method gets called just after component_problem method call
+        # {autocorrect} gets called just after {component_problem}.
         def autocorrect(_node)
           return if @offensive_nodes.nil?
 
@@ -192,7 +192,7 @@ module RuboCop
           corrector.remove(range_with_surrounding_space(range: node1.source_range, side: :left))
         end
 
-        # Returns precedence index and component's index to properly reorder and group during autocorrect
+        # Returns precedence index and component's index to properly reorder and group during autocorrect.
         def get_state(node1)
           @present_components.each_with_index do |comp, idx|
             return [idx, comp.index(node1), comp] if comp.member?(node1)
@@ -228,7 +228,7 @@ module RuboCop
           nil
         end
 
-        # Method to format message for reporting component precedence violations
+        # Method to format message for reporting component precedence violations.
         def component_problem(c1, c2)
           return if COMPONENT_ALLOWLIST.include?(@formula_name)
 
@@ -238,7 +238,7 @@ module RuboCop
         end
 
         # Node pattern method to match
-        # `depends_on` variants
+        # `depends_on` variants.
         def_node_matcher :depends_on_node?, <<~EOS
           {(if _ (send nil? :depends_on ...) nil?)
            (send nil? :depends_on ...)}

Library/Homebrew/rubocops/conflicts.rb

@@ -7,7 +7,7 @@ require "extend/string"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits versioned Formulae for `conflicts_with`.
+      # This cop audits versioned formulae for `conflicts_with`.
       class Conflicts < FormulaCop
         MSG = "Versioned formulae should not use `conflicts_with`. " \
               "Use `keg_only :versioned_formula` instead."

Library/Homebrew/rubocops/dependency_order.rb

@@ -6,10 +6,10 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop checks for correct order of `depends_on` in Formulae.
+      # This cop checks for correct order of `depends_on` in formulae.
       #
       # precedence order:
-      # build-time > run-time > normal > recommended > optional
+      # build-time > test > normal > recommended > optional
       class DependencyOrder < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           check_dependency_nodes_order(body_node)
@@ -61,8 +61,8 @@ module RuboCop
         end
 
         # `depends_on :apple if build.with? "foo"` should always be defined
-        #  after `depends_on :foo`
-        # This method reorders dependencies array according to above rule
+        #  after `depends_on :foo`.
+        # This method reorders the dependencies array according to the above rule.
         def sort_conditional_dependencies!(ordered)
           length = ordered.size
           idx = 0
@@ -86,8 +86,8 @@ module RuboCop
           ordered
         end
 
-        # Verify actual order of sorted `depends_on` nodes in source code
-        # Else raise RuboCop problem
+        # Verify actual order of sorted `depends_on` nodes in source code;
+        # raise RuboCop problem otherwise.
         def verify_order_in_source(ordered)
           ordered.each_with_index do |dependency_node_1, idx|
             l1 = line_number(dependency_node_1)
@@ -104,7 +104,7 @@ module RuboCop
         end
 
         # Node pattern method to match
-        # `depends_on` variants
+        # `depends_on` variants.
         def_node_matcher :depends_on_node?, <<~EOS
           {(if _ (send nil? :depends_on ...) nil?)
            (send nil? :depends_on ...)}
@@ -168,7 +168,7 @@ module RuboCop
                   "\"#{dependency_name(c2)}\" (line #{line_number(c2)})"
         end
 
-        # Reorder two nodes in the source, using the corrector instance in autocorrect method
+        # Reorder two nodes in the source, using the corrector instance in the {autocorrect} method.
         def reorder_components(corrector, node1, node2)
           indentation = " " * (start_column(node2) - line_start_column(node2))
           line_breaks = "\n"

Library/Homebrew/rubocops/deprecate_disable.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits deprecate! date and disable! date
+      # This cop audits `deprecate!` and `disable!` dates.
       class DeprecateDisableDate < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           [:deprecate!, :disable!].each do |method|
@@ -36,7 +36,7 @@ module RuboCop
         EOS
       end
 
-      # This cop audits deprecate! reason
+      # This cop audits `deprecate!` and `disable!` reasons.
       class DeprecateDisableReason < FormulaCop
         PUNCTUATION_MARKS = %w[. ! ?].freeze
 

Library/Homebrew/rubocops/extend/formula.rb

@@ -26,7 +26,7 @@ module RuboCop
 
       @registry = Cop.registry
 
-      # This method is called by RuboCop and is the main entry point
+      # This method is called by RuboCop and is the main entry point.
       def on_class(node)
         @file_path = processed_source.buffer.name
         return unless file_path_allowed?
@@ -39,8 +39,9 @@ module RuboCop
       end
 
       # Yields to block when there is a match.
+      #
       # @param urls [Array] url/mirror method call nodes
-      # @param regex [Regexp] pattern to match urls
+      # @param regex [Regexp] pattern to match URLs
       def audit_urls(urls, regex)
         urls.each do |url_node|
           url_string_node = parameters(url_node).first
@@ -53,7 +54,7 @@ module RuboCop
         end
       end
 
-      # Returns all string nodes among the descendants of given node
+      # Returns all string nodes among the descendants of given node.
       def find_strings(node)
         return [] if node.nil?
         return [node] if node.str_type?
@@ -61,7 +62,7 @@ module RuboCop
         node.each_descendant(:str)
       end
 
-      # Returns method_node matching method_name
+      # Returns method_node matching method_name.
       def find_node_method_by_name(node, method_name)
         return if node.nil?
 
@@ -78,13 +79,13 @@ module RuboCop
         nil
       end
 
-      # Set the given node as the offending node when required in custom cops
+      # Sets the given node as the offending node when required in custom cops.
       def offending_node(node)
         @offensive_node = node
         @offense_source_range = node.source_range
       end
 
-      # Returns an array of method call nodes matching method_name inside node with depth first order (Children nodes)
+      # Returns an array of method call nodes matching method_name inside node with depth first order (child nodes).
       def find_method_calls_by_name(node, method_name)
         return if node.nil?
 
@@ -106,7 +107,7 @@ module RuboCop
       #
       # - matches function call: `foo(*args, **kwargs)`
       # - does not match method calls: `foo.bar(*args, **kwargs)`
-      # - returns every function calls if no func_name is passed
+      # - returns every function call if no func_name is passed
       def find_every_func_call_by_name(node, func_name = nil)
         return if node.nil?
 
@@ -116,7 +117,7 @@ module RuboCop
       end
 
       # Given a method_name and arguments, yields to a block with
-      # matching method passed as a parameter to the block
+      # matching method passed as a parameter to the block.
       def find_method_with_args(node, method_name, *args)
         methods = find_every_method_call_by_name(node, method_name)
         methods.each do |method|
@@ -167,6 +168,7 @@ module RuboCop
       end
 
       # Returns nil if does not depend on dependency_name.
+      #
       # @param dependency_name dependency's name
       def depends_on?(dependency_name, *types)
         types = [:any] if types.empty?
@@ -243,12 +245,12 @@ module RuboCop
         (hash (pair ({str sym} %1) (...)))
       EOS
 
-      # To compare node with appropriate Ruby variable
+      # To compare node with appropriate Ruby variable.
       def node_equals?(node, var)
         node == Parser::CurrentRuby.parse(var.inspect)
       end
 
-      # Returns a block named block_name inside node
+      # Returns a block named block_name inside node.
       def find_block(node, block_name)
         return if node.nil?
 
@@ -265,7 +267,7 @@ module RuboCop
         nil
       end
 
-      # Returns an array of block nodes named block_name inside node
+      # Returns an array of block nodes named block_name inside node.
       def find_blocks(node, block_name)
         return if node.nil?
 
@@ -307,7 +309,7 @@ module RuboCop
         nil
       end
 
-      # Check if a method is called inside a block
+      # Check if a method is called inside a block.
       def method_called_in_block?(node, method_name)
         block_body = node.children[2]
         block_body.each_child_node(:send) do |call_node|
@@ -336,7 +338,7 @@ module RuboCop
         false
       end
 
-      # Check if method_name is called among every descendant node of given node
+      # Check if method_name is called among every descendant node of given node.
       def method_called_ever?(node, method_name)
         node.each_descendant(:send) do |call_node|
           next unless call_node.method_name == method_name
@@ -348,7 +350,7 @@ module RuboCop
         false
       end
 
-      # Checks for precedence, returns the first pair of precedence violating nodes
+      # Checks for precedence; returns the first pair of precedence-violating nodes.
       def check_precedence(first_nodes, next_nodes)
         next_nodes.each do |each_next_node|
           first_nodes.each do |each_first_node|
@@ -358,7 +360,7 @@ module RuboCop
         nil
       end
 
-      # If first node does not precede next_node, sets appropriate instance variables for reporting
+      # If first node does not precede next_node, sets appropriate instance variables for reporting.
       def component_precedes?(first_node, next_node)
         return false if line_number(first_node) < line_number(next_node)
 
@@ -367,7 +369,7 @@ module RuboCop
         true
       end
 
-      # Check if negation is present in the given node
+      # Check if negation is present in the given node.
       def expression_negated?(node)
         return false unless node.parent&.send_type?
         return false unless node.parent.method_name.equal?(:!)
@@ -375,12 +377,12 @@ module RuboCop
         offending_node(node.parent)
       end
 
-      # Return all the caveats' string nodes in an array
+      # Return all the caveats' string nodes in an array.
       def caveats_strings
         find_strings(find_method_def(@body, :caveats))
       end
 
-      # Returns the array of arguments of the method_node
+      # Returns the array of arguments of the method_node.
       def parameters(method_node)
         method_node.arguments if method_node.send_type? || method_node.block_type?
       end
@@ -403,7 +405,7 @@ module RuboCop
         end
       end
 
-      # Returns the sha256 str node given a sha256 call node
+      # Returns the sha256 str node given a sha256 call node.
       def get_checksum_node(call)
         return if parameters(call).empty? || parameters(call).nil?
 
@@ -415,7 +417,7 @@ module RuboCop
         end
       end
 
-      # Yields to a block with comment text as parameter
+      # Yields to a block with comment text as parameter.
       def audit_comments
         @processed_source.comments.each do |comment_node|
           @offensive_node = comment_node
@@ -424,46 +426,46 @@ module RuboCop
         end
       end
 
-      # Returns the ending position of the node in source code
+      # Returns the ending position of the node in source code.
       def end_column(node)
         node.source_range.end_pos
       end
 
-      # Returns the class node's name, nil if not a class node
+      # Returns the class node's name, or nil if not a class node.
       def class_name(node)
         @offensive_node = node
         @offense_source_range = node.source_range
         node.const_name
       end
 
-      # Returns the method name for a def node
+      # Returns the method name for a def node.
       def method_name(node)
         node.children[0] if node.def_type?
       end
 
-      # Returns the node size in the source code
+      # Returns the node size in the source code.
       def size(node)
         node.source_range.size
       end
 
-      # Returns the block length of the block node
+      # Returns the block length of the block node.
       def block_size(block)
         block.loc.end.line - block.loc.begin.line
       end
 
-      # Returns true if the formula is versioned
+      # Returns true if the formula is versioned.
       def versioned_formula?
         @formula_name.include?("@")
       end
 
-      # Returns printable component name
+      # Returns printable component name.
       def format_component(component_node)
         return component_node.method_name if component_node.send_type? || component_node.block_type?
 
         method_name(component_node) if component_node.def_type?
       end
 
-      # Returns the formula tap
+      # Returns the formula tap.
       def formula_tap
         return unless match_obj = @file_path.match(%r{/(homebrew-\w+)/})
 

Library/Homebrew/rubocops/formula_desc.rb

@@ -8,8 +8,8 @@ require "extend/string"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits `desc` in Formulae.
-      # See the `DescHelper` module for details of the checks.
+      # This cop audits `desc` in formulae.
+      # See the {DescHelper} module for details of the checks.
       class Desc < FormulaCop
         include DescHelper
 

Library/Homebrew/rubocops/homepage.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits the `homepage` URL in Formulae.
+      # This cop audits the `homepage` URL in formulae.
       class Homepage < FormulaCop
         def audit_formula(_node, _class_node, _parent_class_node, body_node)
           homepage_node = find_node_method_by_name(body_node, :homepage)
@@ -23,7 +23,7 @@ module RuboCop
           end
 
           case homepage
-          # Check for http:// GitHub homepage urls, https:// is preferred.
+          # Check for http:// GitHub homepage URLs, https:// is preferred.
           # Note: only check homepages that are repo pages, not *.github.com hosts
           when %r{^http://github.com/}
             problem "Please use https:// for #{homepage}"

Library/Homebrew/rubocops/lines.rb

@@ -110,7 +110,7 @@ module RuboCop
         end
       end
 
-      # This cop makes sure that options are used idiomatically.
+      # This cop makes sure that `option`s are used idiomatically.
       #
       # @api private
       class OptionDeclarations < FormulaCop
@@ -320,7 +320,7 @@ module RuboCop
         EOS
       end
 
-      # This cop makes sure that python versions are consistent.
+      # This cop makes sure that Python versions are consistent.
       #
       # @api private
       class PythonVersions < FormulaCop

Library/Homebrew/rubocops/livecheck.rb

@@ -41,7 +41,7 @@ module RuboCop
         end
       end
 
-      # This cop ensures that a `url` is specified in the livecheck block.
+      # This cop ensures that a `url` is specified in the `livecheck` block.
       #
       # @api private
       class LivecheckUrlProvided < FormulaCop
@@ -124,7 +124,7 @@ module RuboCop
         end
       end
 
-      # This cop ensures that the `regex` call in the livecheck block uses parentheses.
+      # This cop ensures that the `regex` call in the `livecheck` block uses parentheses.
       #
       # @api private
       class LivecheckRegexParentheses < FormulaCop
@@ -188,7 +188,7 @@ module RuboCop
       end
 
       # This cop ensures that a `regex` is provided when `strategy :page_match` is specified
-      # in the livecheck block.
+      # in the `livecheck` block.
       #
       # @api private
       class LivecheckRegexIfPageMatch < FormulaCop

Library/Homebrew/rubocops/options.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits `options` in Formulae.
+      # This cop audits `option`s in formulae.
       class Options < FormulaCop
         DEPRECATION_MSG = "macOS has been 64-bit only since 10.6 so 32-bit options are deprecated."
         UNI_DEPRECATION_MSG = "macOS has been 64-bit only since 10.6 so universal options are deprecated."

Library/Homebrew/rubocops/patches.rb

@@ -7,7 +7,7 @@ require "extend/string"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits patches in Formulae.
+      # This cop audits `patch`es in formulae.
       class Patches < FormulaCop
         def audit_formula(node, _class_node, _parent_class_node, body)
           @full_source_content = source_buffer(node).source

Library/Homebrew/rubocops/shared/desc_helper.rb

@@ -5,7 +5,7 @@ require "rubocops/shared/helper_functions"
 
 module RuboCop
   module Cop
-    # This module performs common checks the `desc` field in both Formulae and Casks.
+    # This module performs common checks the `desc` field in both formulae and casks.
     #
     # @api private
     module DescHelper

Library/Homebrew/rubocops/shared/helper_functions.rb

@@ -10,7 +10,7 @@ module RuboCop
       include RangeHelp
 
       # Checks for regex match of pattern in the node and
-      # sets the appropriate instance variables to report the match
+      # sets the appropriate instance variables to report the match.
       def regex_match_group(node, pattern)
         string_repr = string_content(node).encode("UTF-8", invalid: :replace)
         match_object = string_repr.match(pattern)
@@ -31,27 +31,27 @@ module RuboCop
         match_object
       end
 
-      # Returns the begin position of the node's line in source code
+      # Returns the begin position of the node's line in source code.
       def line_start_column(node)
         node.source_range.source_buffer.line_range(node.loc.line).begin_pos
       end
 
-      # Returns the begin position of the node in source code
+      # Returns the begin position of the node in source code.
       def start_column(node)
         node.source_range.begin_pos
       end
 
-      # Returns the line number of the node
+      # Returns the line number of the node.
       def line_number(node)
         node.loc.line
       end
 
-      # Source buffer is required as an argument to report style violations
+      # Source buffer is required as an argument to report style violations.
       def source_buffer(node)
         node.source_range.source_buffer
       end
 
-      # Returns the string representation if node is of type str(plain) or dstr(interpolated) or const
+      # Returns the string representation if node is of type str(plain) or dstr(interpolated) or const.
       def string_content(node)
         case node.type
         when :str

Library/Homebrew/rubocops/text.rb

@@ -156,7 +156,7 @@ module RuboCop
           end
         end
 
-        # Check whether value starts with the formula name and then a "/", " " or EOS
+        # Check whether value starts with the formula name and then a "/", " " or EOS.
         def path_starts_with?(path, starts_with)
           path.match?(%r{^#{Regexp.escape(starts_with)}(/| |$)})
         end

Library/Homebrew/rubocops/urls.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits URLs and mirrors in Formulae.
+      # This cop audits `url`s and `mirror`s in formulae.
       #
       # @api private
       class Urls < FormulaCop
@@ -55,13 +55,13 @@ module RuboCop
           urls = find_every_func_call_by_name(body_node, :url)
           mirrors = find_every_func_call_by_name(body_node, :mirror)
 
-          # Identify livecheck urls, to skip some checks for them
+          # Identify livecheck URLs, to skip some checks for them
           livecheck_url = if (livecheck = find_every_func_call_by_name(body_node, :livecheck).first) &&
                              (livecheck_url = find_every_func_call_by_name(livecheck.parent, :url).first)
             string_content(parameters(livecheck_url).first)
           end
 
-          # GNU urls; doesn't apply to mirrors
+          # GNU URLs; doesn't apply to mirrors
           gnu_pattern = %r{^(?:https?|ftp)://ftpmirror.gnu.org/(.*)}
           audit_urls(urls, gnu_pattern) do |match, url|
             problem "Please use \"https://ftp.gnu.org/gnu/#{match[1]}\" instead of #{url}."
@@ -202,7 +202,7 @@ module RuboCop
             EOS
           end
 
-          # Check to use canonical urls for Debian packages
+          # Check to use canonical URLs for Debian packages
           noncanon_deb_pattern =
             Regexp.union([%r{^https://mirrors\.kernel\.org/debian/},
                           %r{^https://mirrors\.ocf\.berkeley\.edu/debian/},
@@ -211,26 +211,26 @@ module RuboCop
             problem "Please use https://deb.debian.org/debian/ for #{url}"
           end
 
-          # Check for new-url Google Code download urls, https:// is preferred
+          # Check for new-url Google Code download URLs, https:// is preferred
           google_code_pattern = Regexp.union([%r{^http://.*\.googlecode\.com/files.*},
                                               %r{^http://code\.google\.com/}])
           audit_urls(urls, google_code_pattern) do |_, url|
             problem "Please use https:// for #{url}"
           end
 
-          # Check for git:// GitHub repo urls, https:// is preferred.
+          # Check for git:// GitHub repo URLs, https:// is preferred.
           git_gh_pattern = %r{^git://[^/]*github\.com/}
           audit_urls(urls, git_gh_pattern) do |_, url|
             problem "Please use https:// for #{url}"
           end
 
-          # Check for git:// Gitorious repo urls, https:// is preferred.
+          # Check for git:// Gitorious repo URLs, https:// is preferred.
           git_gitorious_pattern = %r{^git://[^/]*gitorious\.org/}
           audit_urls(urls, git_gitorious_pattern) do |_, url|
             problem "Please use https:// for #{url}"
           end
 
-          # Check for http:// GitHub repo urls, https:// is preferred.
+          # Check for http:// GitHub repo URLs, https:// is preferred.
           gh_pattern = %r{^http://github\.com/.*\.git$}
           audit_urls(urls, gh_pattern) do |_, url|
             problem "Please use https:// for #{url}"
@@ -269,7 +269,7 @@ module RuboCop
             EOS
           end
 
-          # Check for Maven Central urls, prefer HTTPS redirector over specific host
+          # Check for Maven Central URLs, prefer HTTPS redirector over specific host
           maven_pattern = %r{https?://(?:central|repo\d+)\.maven\.org/maven2/(.+)$}
           audit_urls(urls, maven_pattern) do |match, url|
             problem "#{url} should be `https://search.maven.org/remotecontent?filepath=#{match[1]}`"
@@ -290,7 +290,7 @@ module RuboCop
         end
       end
 
-      # This cop makes sure that the correct format for PyPi URLs is used.
+      # This cop makes sure that the correct format for PyPI URLs is used.
       #
       # @api private
       class PyPiUrls < FormulaCop
@@ -299,13 +299,13 @@ module RuboCop
           mirrors = find_every_func_call_by_name(body_node, :mirror)
           urls += mirrors
 
-          # Check pypi urls
+          # Check pypi URLs
           pypi_pattern = %r{^https?://pypi.python.org/}
           audit_urls(urls, pypi_pattern) do |_, url|
             problem "use the `Source` url found on PyPI downloads page (`#{get_pypi_url(url)}`)"
           end
 
-          # Require long files.pythonhosted.org urls
+          # Require long files.pythonhosted.org URLs
           pythonhosted_pattern = %r{^https?://files.pythonhosted.org/packages/source/}
           audit_urls(urls, pythonhosted_pattern) do |_, url|
             problem "use the `Source` url found on PyPI downloads page (`#{get_pypi_url(url)}`)"
@@ -319,7 +319,7 @@ module RuboCop
         end
       end
 
-      # This cop makes sure that git urls have both a `revision`.
+      # This cop makes sure that git URLs have a `revision`.
       #
       # @api private
       class GitUrls < FormulaCop
@@ -342,7 +342,7 @@ module RuboCop
     end
 
     module FormulaAuditStrict
-      # This cop makes sure that git urls have both a `tag`.
+      # This cop makes sure that git URLs have a `tag`.
       #
       # @api private
       class GitUrls < FormulaCop

Library/Homebrew/rubocops/uses_from_macos.rb

@@ -6,11 +6,15 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop audits `uses_from_macos` dependencies in formulae
+      # This cop audits `uses_from_macos` dependencies in formulae.
       class UsesFromMacos < FormulaCop
         # Generate with:
+        #
+        # ```
         # brew ruby -e 'puts Formula.select {|f| f.keg_only_reason&.provided_by_macos? }.map(&:name).sort.join("\n")'
-        # Not done at runtime as its too slow and RuboCop doesn't have access.
+        # ```
+        #
+        # Not done at runtime as it's too slow and RuboCop doesn't have access.
         PROVIDED_BY_MACOS_FORMULAE = %w[
           apr
           bc
@@ -57,8 +61,8 @@ module RuboCop
           zlib
         ].freeze
 
-        # These formulae aren't keg_only :provided_by_macos but are provided by
-        # macOS (or very similarly e.g. OpenSSL where system provides LibreSSL)
+        # These formulae aren't `keg_only :provided_by_macos` but are provided by
+        # macOS (or very similarly, e.g. OpenSSL where system provides LibreSSL).
         # TODO: consider making some of these keg-only.
         ALLOWED_USES_FROM_MACOS_DEPS = (PROVIDED_BY_MACOS_FORMULAE + %w[
           bash

Library/Homebrew/rubocops/version.rb

@@ -6,7 +6,7 @@ require "rubocops/extend/formula"
 module RuboCop
   module Cop
     module FormulaAudit
-      # This cop makes sure that a version is in the correct format.
+      # This cop makes sure that a `version` is in the correct format.
       #
       # @api private
       class Version < FormulaCop

Library/Homebrew/shims/super/cc

@@ -381,8 +381,8 @@ class Cmd
     paths.map! { |path| prefix + path }
   end
 
-  # Unlike path_flags, do not prune non-existent directories.
-  # formula.lib for example does not yet exist, but should not be pruned.
+  # Unlike {path_flags}, do not prune non-existent directories.
+  # `formula.lib` for example does not yet exist, but should not be pruned.
   def rpath_flags(prefix, paths)
     paths.uniq.map { |path| prefix + path }
   end

Library/Homebrew/software_spec.rb

@@ -354,7 +354,7 @@ class BottleSpecification
     cellar == :any || cellar == :any_skip_relocation || cellar == HOMEBREW_CELLAR.to_s
   end
 
-  # Does the {Bottle} this BottleSpecification belongs to need to be relocated?
+  # Does the {Bottle} this {BottleSpecification} belongs to need to be relocated?
   def skip_relocation?
     cellar == :any_skip_relocation
   end