admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

Improve documentation comments

Browse Source
This commit is contained in:
Sam Ford 2021-08-10 18:38:21 -04:00
parent f2bd39ccef
commit c936a9420e
No known key found for this signature in database
GPG Key ID: 95209E46C7FFDEFE
7 changed files with 77 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
Library/Homebrew/livecheck/strategy.rb
View File

@ -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 = []

10
Library/Homebrew/livecheck/strategy/electron_builder.rb
View File

@ -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(

23
Library/Homebrew/livecheck/strategy/extract_plist.rb
View File

@ -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)

2
Library/Homebrew/livecheck/strategy/git.rb
View File

@ -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(

21
Library/Homebrew/livecheck/strategy/header_match.rb
View File

@ -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,

18
Library/Homebrew/livecheck/strategy/page_match.rb
View File

@ -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 {

19
Library/Homebrew/livecheck/strategy/sparkle.rb
View File

@ -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"