From c936a9420eed710d955346cbfb76140a24d1b551 Mon Sep 17 00:00:00 2001 From: Sam Ford <1584702+samford@users.noreply.github.com> Date: Tue, 10 Aug 2021 18:38:21 -0400 Subject: [PATCH] Improve documentation comments --- Library/Homebrew/livecheck/strategy.rb | 32 ++++++++++++------- .../livecheck/strategy/electron_builder.rb | 10 +++--- .../livecheck/strategy/extract_plist.rb | 23 +++++++------ Library/Homebrew/livecheck/strategy/git.rb | 2 +- .../livecheck/strategy/header_match.rb | 21 +++++++----- .../Homebrew/livecheck/strategy/page_match.rb | 18 ++++++----- .../Homebrew/livecheck/strategy/sparkle.rb | 19 +++++++---- 7 files changed, 77 insertions(+), 48 deletions(-) diff --git a/Library/Homebrew/livecheck/strategy.rb b/Library/Homebrew/livecheck/strategy.rb index b77610d0c4..515cdb80a1 100644 --- 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 = [] diff --git a/Library/Homebrew/livecheck/strategy/electron_builder.rb b/Library/Homebrew/livecheck/strategy/electron_builder.rb index 5c27824235..62baf90c1c 100644 --- 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( diff --git a/Library/Homebrew/livecheck/strategy/extract_plist.rb b/Library/Homebrew/livecheck/strategy/extract_plist.rb index c9a12b0ce6..81ad951c1a 100644 --- 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) diff --git a/Library/Homebrew/livecheck/strategy/git.rb b/Library/Homebrew/livecheck/strategy/git.rb index d68853ab9b..b4b7510199 100644 --- 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( diff --git a/Library/Homebrew/livecheck/strategy/header_match.rb b/Library/Homebrew/livecheck/strategy/header_match.rb index 66d7bccfbe..d1d2d36f3c 100644 --- 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, diff --git a/Library/Homebrew/livecheck/strategy/page_match.rb b/Library/Homebrew/livecheck/strategy/page_match.rb index 873d54a4fa..3b5d17f6d9 100644 --- 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 { diff --git a/Library/Homebrew/livecheck/strategy/sparkle.rb b/Library/Homebrew/livecheck/strategy/sparkle.rb index 9e7cf4f1cf..42b0460c9a 100644 --- 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"