GithubLatest: Update documentation

Library/Homebrew/livecheck/strategy/github_latest.rb

@@ -5,7 +5,8 @@ module Homebrew
   module Livecheck
     module Strategy
       # The {GithubLatest} strategy identifies versions of software at
-      # github.com by checking a repository's "latest" release page.
+      # github.com by checking a repository's "latest" release using the
+      # GitHub API.
       #
       # GitHub URLs take a few different formats:
       #
@@ -13,22 +14,16 @@ module Homebrew
       # * `https://github.com/example/example/archive/v1.2.3.tar.gz`
       # * `https://github.com/downloads/example/example/example-1.2.3.tar.gz`
       #
-      # A repository's `/releases/latest` URL normally redirects to a release
+      # {GithubLatest} should only be used when the upstream repository has a
-      # tag (e.g., `/releases/tag/1.2.3`). When there isn't a "latest" release,
+      # "latest" release for a suitable version and the strategy is necessary
-      # it will redirect to the `/releases` page.
+      # or appropriate (e.g. {Git} returns an unreleased version or the
+      # `stable` URL is a release asset). The strategy can only be applied by
+      # using `strategy :github_latest` in a `livecheck` block.
       #
-      # This strategy should only be used when we know the upstream repository
+      # The default regex identifies versions like `1.2.3`/`v1.2.3` in the
-      # has a "latest" release and the tagged release is appropriate to use
+      # release's tag name. This is a common tag format but a modified regex
-      # (e.g., "latest" isn't wrongly pointing to an unstable version, not
+      # can be provided in a `livecheck` block to override the default if a
-      # picking up the actual latest version, etc.). The strategy can only be
+      # repository uses a different format (e.g. `1.2.3d`, `1.2.3-4`, etc.).
-      # applied by using `strategy :github_latest` in a `livecheck` block.
-      #
-      # The default regex identifies versions like `1.2.3`/`v1.2.3` in `href`
-      # attributes containing the tag URL (e.g.,
-      # `/example/example/releases/tag/v1.2.3`). This is a common tag format
-      # but a modified regex can be provided in a `livecheck` block to override
-      # the default if a repository uses a different format (e.g.,
-      # `example-1.2.3`, `1.2.3d`, `1.2.3-4`, etc.).
       #
       # @api public
       class GithubLatest
@@ -50,8 +45,9 @@ module Homebrew
         # isn't provided.
         DEFAULT_REGEX = /v?(\d+(?:\.\d+)+)/i.freeze
 
-        # Keys in the JSON that could contain the version.
+        # Keys in the release JSON that could contain the version.
-        VERSION_KEYS = ["name", "tag_name"].freeze
+        # Tag name first since that is closer to other livechecks.
+        VERSION_KEYS = ["tag_name", "name"].freeze
 
         # Whether the strategy can be applied to the provided URL.
         #
@@ -83,17 +79,17 @@ module Homebrew
           values
         end
 
-        # Uses the regex to match release information in content or, if a block is
+        # Uses a regex to match the version from release JSON or, if a block is
-        # provided, passes the page content to the block to handle matching.
+        # provided, passes the JSON to the block to handle matching. With
-        # With either approach, an array of unique matches is returned.
+        # either approach, an array of unique matches is returned.
         #
-        # @param content [Array] list of releases
+        # @param content [Array, Hash] list of releases or a single release
         # @param regex [Regexp] a regex used for matching versions in the content
         # @param block [Proc, nil] a block to match the content
         # @return [Array]
         sig {
           params(
-            content: T::Array[T::Hash[String, T.untyped]],
+            content: T.any(T::Array[T::Hash[String, T.untyped]], T::Hash[String, T.untyped]),
             regex:   Regexp,
             block:   T.nilable(Proc),
           ).returns(T::Array[String])
@@ -108,19 +104,23 @@ module Homebrew
             return Strategy.handle_block_return(block_return_value)
           end
 
+          content = [content] unless content.is_a?(Array)
           content.reject(&:blank?).map do |release|
             next if release["draft"] || release["prerelease"]
 
             value = T.let(nil, T.untyped)
             VERSION_KEYS.find do |key|
-              value = release[key]&.match(regex)&.to_s
+              match = release[key]&.match(regex)
+              next if match.blank?
+
+              value = match[1]
             end
             value
           end.compact.uniq
         end
 
-        # Generates a URL and regex (if one isn't provided) and passes them
+        # Generates the GitHub API URL for the repository's "latest" release
-        # to {PageMatch.find_versions} to identify versions in the content.
+        # and identifies the version from the JSON response.
         #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
@@ -142,7 +142,7 @@ module Homebrew
           match_data[:url] = generated[:url]
 
           release = GitHub.get_latest_release(generated[:username], generated[:repository])
-          versions_from_content([release], regex, &block).each do |match_text|
+          versions_from_content(release, regex, &block).each do |match_text|
             match_data[:matches][match_text] = Version.new(match_text)
           end