Improve documentation comments

Library/Homebrew/livecheck/strategy.rb

@@ -14,7 +14,7 @@ module Homebrew
 
       module_function
 
-      # Strategy priorities informally range from 1 to 10, where 10 is the
+      # {Strategy} priorities informally range from 1 to 10, where 10 is the
       # highest priority. 5 is the default priority because it's roughly in
       # the middle of this range. Strategies with a priority of 0 (or lower)
       # are ignored.
@@ -32,10 +32,10 @@ module Homebrew
       # The `curl` process will sometimes hang indefinitely (despite setting
       # the `--max-time` argument) and it needs to be quit for livecheck to
       # continue. This value is used to set the `timeout` argument on
-      # `Utils::Curl` method calls in `Strategy`.
+      # `Utils::Curl` method calls in {Strategy}.
       CURL_PROCESS_TIMEOUT = CURL_MAX_TIME + 5
 
-      # Baseline `curl` arguments used in `Strategy` methods.
+      # Baseline `curl` arguments used in {Strategy} methods.
       DEFAULT_CURL_ARGS = [
         # Follow redirections to handle mirrors, relocations, etc.
         "--location",
@@ -60,7 +60,7 @@ module Homebrew
         "--include",
       ] + DEFAULT_CURL_ARGS).freeze
 
-      # Baseline `curl` options used in `Strategy` methods.
+      # Baseline `curl` options used in {Strategy} methods.
       DEFAULT_CURL_OPTIONS = {
         print_stdout: false,
         print_stderr: false,
@@ -81,7 +81,7 @@ module Homebrew
 
       # Creates and/or returns a `@strategies` `Hash`, which maps a snake
       # case strategy name symbol (e.g. `:page_match`) to the associated
-      # {Strategy}.
+      # strategy.
       #
       # At present, this should only be called after tap strategies have been
       # loaded, otherwise livecheck won't be able to use them.
@@ -102,12 +102,12 @@ module Homebrew
       end
       private_class_method :strategies
 
-      # Returns the {Strategy} that corresponds to the provided `Symbol` (or
+      # Returns the strategy that corresponds to the provided `Symbol` (or
-      # `nil` if there is no matching {Strategy}).
+      # `nil` if there is no matching strategy).
       #
-      # @param symbol [Symbol] the strategy name in snake case as a `Symbol`
+      # @param symbol [Symbol, nil] the strategy name in snake case as a
-      #   (e.g. `:page_match`)
+      #   `Symbol` (e.g. `:page_match`)
-      # @return [Strategy, nil]
+      # @return [Class, nil]
       sig { params(symbol: T.nilable(Symbol)).returns(T.nilable(T.untyped)) }
       def from_symbol(symbol)
         strategies[symbol] if symbol.present?
@@ -116,10 +116,14 @@ module Homebrew
       # Returns an array of strategies that apply to the provided URL.
       #
       # @param url [String] the URL to check for matching strategies
-      # @param livecheck_strategy [Symbol] a {Strategy} symbol from the
+      # @param livecheck_strategy [Symbol] a strategy symbol from the
+      #   `livecheck` block
+      # @param url_provided [Boolean] whether a url is provided in the
       #   `livecheck` block
       # @param regex_provided [Boolean] whether a regex is provided in the
       #   `livecheck` block
+      # @param block_provided [Boolean] whether a `strategy` block is provided
+      #   in the `livecheck` block
       # @return [Array]
       sig {
         params(
@@ -154,6 +158,12 @@ module Homebrew
         end
       end
 
+      # Collects HTTP response headers, starting with the provided URL.
+      # Redirections will be followed and all the response headers are
+      # collected into an array of hashes.
+      #
+      # @param url [String] the URL to fetch
+      # @return [Array]
       sig { params(url: String).returns(T::Array[T::Hash[String, String]]) }
       def self.page_headers(url)
         headers = []

Library/Homebrew/livecheck/strategy/electron_builder.rb

@@ -7,6 +7,9 @@ module Homebrew
       # The {ElectronBuilder} strategy fetches content at a URL and parses
       # it as an electron-builder appcast in YAML format.
       #
+      # This strategy is not applied automatically and it's necessary to use
+      # `strategy :electron_builder` in a `livecheck` block to apply it.
+      #
       # @api private
       class ElectronBuilder
         extend T::Sig
@@ -14,8 +17,7 @@ module Homebrew
         NICE_NAME = "electron-builder"
 
         # A priority of zero causes livecheck to skip the strategy. We do this
-        # for {ElectronBuilder} so we can selectively apply the strategy using
+        # for {ElectronBuilder} so we can selectively apply it when appropriate.
-        # `strategy :electron_builder` in a `livecheck` block.
         PRIORITY = 0
 
         # The `Regexp` used to determine if the strategy applies to the URL.
@@ -54,10 +56,10 @@ module Homebrew
           version.present? ? [version] : []
         end
 
-        # Checks the content at the URL for new versions.
+        # Checks the YAML content at the URL for new versions.
         #
         # @param url [String] the URL of the content to check
-        # @param regex [Regexp] a regex used for matching versions in content
+        # @param regex [Regexp, nil] a regex used for matching versions
         # @return [Hash]
         sig {
           params(

Library/Homebrew/livecheck/strategy/extract_plist.rb

@@ -8,26 +8,31 @@ require_relative "page_match"
 module Homebrew
   module Livecheck
     module Strategy
-      # The {ExtractPlist} strategy downloads the file at a URL and
+      # The {ExtractPlist} strategy downloads the file at a URL and extracts
-      # extracts versions from contained `.plist` files.
+      # versions from contained `.plist` files using {UnversionedCaskChecker}.
+      #
+      # In practice, this strategy operates by downloading very large files,
+      # so it's both slow and data-intensive. As such, the {ExtractPlist}
+      # strategy should only be used as an absolute last resort.
+      #
+      # This strategy is not applied automatically and it's necessary to use
+      # `strategy :extract_plist` in a `livecheck` block to apply it.
       #
       # @api private
       class ExtractPlist
         extend T::Sig
 
-        # A priority of zero causes livecheck to skip the strategy. We only
+        # A priority of zero causes livecheck to skip the strategy. We do this
-        # apply {ExtractPlist} using `strategy :extract_plist` in a `livecheck` block,
+        # for {ExtractPlist} so we can selectively apply it when appropriate.
-        # as we can't automatically determine when this can be successfully
-        # applied to a URL without fetching the content.
         PRIORITY = 0
 
         # The `Regexp` used to determine if the strategy applies to the URL.
         URL_MATCH_REGEX = %r{^https?://}i.freeze
 
         # Whether the strategy can be applied to the provided URL.
-        # The strategy will technically match any HTTP URL but is
+        #
-        # only usable with a `livecheck` block containing a regex
+        # @param url [String] the URL to match against
-        # or block.
+        # @return [Boolean]
         sig { params(url: String).returns(T::Boolean) }
         def self.match?(url)
           URL_MATCH_REGEX.match?(url)

Library/Homebrew/livecheck/strategy/git.rb

@@ -118,7 +118,7 @@ module Homebrew
         # strings and parses the remaining text as a {Version}.
         #
         # @param url [String] the URL of the Git repository to check
-        # @param regex [Regexp] the regex to use for matching versions
+        # @param regex [Regexp, nil] a regex used for matching versions
         # @return [Hash]
         sig {
           params(

Library/Homebrew/livecheck/strategy/header_match.rb

@@ -9,16 +9,17 @@ module Homebrew
       # The {HeaderMatch} strategy follows all URL redirections and scans
       # the resulting headers for matching text using the provided regex.
       #
+      # This strategy is not applied automatically and it's necessary to use
+      # `strategy :header_match` in a `livecheck` block to apply it.
+      #
       # @api private
       class HeaderMatch
         extend T::Sig
 
         NICE_NAME = "Header match"
 
-        # A priority of zero causes livecheck to skip the strategy. We only
+        # A priority of zero causes livecheck to skip the strategy. We do this
-        # apply {HeaderMatch} using `strategy :header_match` in a `livecheck`
+        # for {HeaderMatch} so we can selectively apply it when appropriate.
-        # block, as we can't automatically determine when this can be
-        # successfully applied to a URL.
         PRIORITY = 0
 
         # The `Regexp` used to determine if the strategy applies to the URL.
@@ -28,9 +29,9 @@ module Homebrew
         DEFAULT_HEADERS_TO_CHECK = ["content-disposition", "location"].freeze
 
         # Whether the strategy can be applied to the provided URL.
-        # The strategy will technically match any HTTP URL but is
+        #
-        # only usable with a `livecheck` block containing a regex
+        # @param url [String] the URL to match against
-        # or block.
+        # @return [Boolean]
         sig { params(url: String).returns(T::Boolean) }
         def self.match?(url)
           URL_MATCH_REGEX.match?(url)
@@ -39,7 +40,7 @@ module Homebrew
         # Identify versions from HTTP headers.
         #
         # @param headers [Hash] a hash of HTTP headers to check for versions
-        # @param regex [Regexp, nil] a regex to use to identify versions
+        # @param regex [Regexp, nil] a regex for matching versions
         # @return [Array]
         sig {
           params(
@@ -71,6 +72,10 @@ module Homebrew
 
         # Checks the final URL for new versions after following all redirections,
         # using the provided regex for matching.
+        #
+        # @param url [String] the URL to fetch
+        # @param regex [Regexp, nil] a regex used for matching versions
+        # @return [Hash]
         sig {
           params(
             url:   String,

Library/Homebrew/livecheck/strategy/page_match.rb

@@ -11,9 +11,8 @@ module Homebrew
       # strategies apply to a given URL. Though {PageMatch} will technically
       # match any HTTP URL, the strategy also requires a regex to function.
       #
-      # The {find_versions} method is also used within other
+      # The {find_versions} method is also used within other strategies,
-      # strategies, to handle the process of identifying version text in
+      # to handle the process of identifying version text in content.
-      # content.
       #
       # @api public
       class PageMatch
@@ -22,16 +21,19 @@ module Homebrew
         NICE_NAME = "Page match"
 
         # A priority of zero causes livecheck to skip the strategy. We do this
-        # for PageMatch so we can selectively apply the strategy only when a
+        # for {PageMatch} so we can selectively apply it only when a regex is
-        # regex is provided in a `livecheck` block.
+        # provided in a `livecheck` block.
         PRIORITY = 0
 
         # The `Regexp` used to determine if the strategy applies to the URL.
         URL_MATCH_REGEX = %r{^https?://}i.freeze
 
         # Whether the strategy can be applied to the provided URL.
-        # PageMatch will technically match any HTTP URL but is only
+        # {PageMatch} will technically match any HTTP URL but is only
         # usable with a `livecheck` block containing a regex.
+        #
+        # @param url [String] the URL to match against
+        # @return [Boolean]
         sig { params(url: String).returns(T::Boolean) }
         def self.match?(url)
           URL_MATCH_REGEX.match?(url)
@@ -71,8 +73,8 @@ module Homebrew
         # regex for matching.
         #
         # @param url [String] the URL of the content to check
-        # @param regex [Regexp] a regex used for matching versions in content
+        # @param regex [Regexp] a regex used for matching versions
-        # @param provided_content [String] page content to use in place of
+        # @param provided_content [String, nil] page content to use in place of
         #   fetching via Strategy#page_content
         # @return [Hash]
         sig {

Library/Homebrew/livecheck/strategy/sparkle.rb

@@ -9,23 +9,24 @@ module Homebrew
       # The {Sparkle} strategy fetches content at a URL and parses
       # it as a Sparkle appcast in XML format.
       #
+      # This strategy is not applied automatically and it's necessary to use
+      # `strategy :sparkle` in a `livecheck` block to apply it.
+      #
       # @api private
       class Sparkle
         extend T::Sig
 
-        # A priority of zero causes livecheck to skip the strategy. We only
+        # A priority of zero causes livecheck to skip the strategy. We do this
-        # apply {Sparkle} using `strategy :sparkle` in a `livecheck` block,
+        # for {Sparkle} so we can selectively apply it when appropriate.
-        # as we can't automatically determine when this can be successfully
-        # applied to a URL without fetching the content.
         PRIORITY = 0
 
         # The `Regexp` used to determine if the strategy applies to the URL.
         URL_MATCH_REGEX = %r{^https?://}i.freeze
 
         # Whether the strategy can be applied to the provided URL.
-        # The strategy will technically match any HTTP URL but is
+        #
-        # only usable with a `livecheck` block containing a regex
+        # @param url [String] the URL to match against
-        # or block.
+        # @return [Boolean]
         sig { params(url: String).returns(T::Boolean) }
         def self.match?(url)
           URL_MATCH_REGEX.match?(url)
@@ -54,6 +55,10 @@ module Homebrew
           delegate short_version: :bundle_version
         end
 
+        # Identify version information from a Sparkle appcast.
+        #
+        # @param content [String] the text of the Sparkle appcast
+        # @return [Item, nil]
         sig { params(content: String).returns(T.nilable(Item)) }
         def self.item_from_content(content)
           require "rexml/document"