Improve documentation comments

2021-08-10 18:38:21 -04:00 · 2021-08-10 18:38:21 -04:00 · c936a9420e
commit c936a9420e
parent f2bd39ccef
7 changed files with 77 additions and 48 deletions
--- a/Library/Homebrew/livecheck/strategy.rb
+++ b/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
-      # `nil` if there is no matching {Strategy}).
+      # Returns the strategy that corresponds to the provided `Symbol` (or
+      # `nil` if there is no matching strategy).
      #
-      # @param symbol [Symbol] the strategy name in snake case as a `Symbol`
-      #   (e.g. `:page_match`)
-      # @return [Strategy, nil]
+      # @param symbol [Symbol, nil] the strategy name in snake case as a
+      #   `Symbol` (e.g. `:page_match`)
+      # @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 = []
--- a/Library/Homebrew/livecheck/strategy/electron_builder.rb
+++ b/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
-        # `strategy :electron_builder` in a `livecheck` block.
+        # for {ElectronBuilder} so we can selectively apply it when appropriate.
        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(
--- a/Library/Homebrew/livecheck/strategy/extract_plist.rb
+++ b/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
-      # extracts versions from contained `.plist` files.
+      # The {ExtractPlist} strategy downloads the file at a URL and extracts
+      # 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
-        # apply {ExtractPlist} using `strategy :extract_plist` in a `livecheck` block,
-        # as we can't automatically determine when this can be successfully
-        # applied to a URL without fetching the content.
+        # A priority of zero causes livecheck to skip the strategy. We do this
+        # for {ExtractPlist} so we can selectively apply it when appropriate.
        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
-        # or block.
+        #
+        # @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)
--- a/Library/Homebrew/livecheck/strategy/git.rb
+++ b/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(
--- a/Library/Homebrew/livecheck/strategy/header_match.rb
+++ b/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
-        # apply {HeaderMatch} using `strategy :header_match` in a `livecheck`
-        # block, as we can't automatically determine when this can be
-        # successfully applied to a URL.
+        # A priority of zero causes livecheck to skip the strategy. We do this
+        # for {HeaderMatch} so we can selectively apply it when appropriate.
        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
-        # or block.
+        #
+        # @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)
@ -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,
--- a/Library/Homebrew/livecheck/strategy/page_match.rb
+++ b/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
-      # strategies, to handle the process of identifying version text in
-      # content.
+      # The {find_versions} method is also used within other strategies,
+      # to handle the process of identifying version text in 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
-        # regex is provided in a `livecheck` block.
+        # for {PageMatch} so we can selectively apply it only when a regex is
+        # 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 provided_content [String] page content to use in place of
+        # @param regex [Regexp] a regex used for matching versions
+        # @param provided_content [String, nil] page content to use in place of
        #   fetching via Strategy#page_content
        # @return [Hash]
        sig {
--- a/Library/Homebrew/livecheck/strategy/sparkle.rb
+++ b/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
-        # apply {Sparkle} using `strategy :sparkle` in a `livecheck` block,
-        # as we can't automatically determine when this can be successfully
-        # applied to a URL without fetching the content.
+        # A priority of zero causes livecheck to skip the strategy. We do this
+        # for {Sparkle} so we can selectively apply it when appropriate.
        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
-        # or block.
+        #
+        # @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)
@ -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"