GithubLatest: Update documentation

Library/Homebrew/livecheck/strategy/github_latest.rb

@@ -5,30 +5,25 @@ 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:
       #
       # * `https://github.com/example/example/releases/download/1.2.3/example-1.2.3.tar.gz`
       # * `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
-      # tag (e.g., `/releases/tag/1.2.3`). When there isn't a "latest" release,
-      # it will redirect to the `/releases` page.
+      # {GithubLatest} should only be used when the upstream repository has a
+      # "latest" release for a suitable version and the strategy is necessary
+      # 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
-      # has a "latest" release and the tagged release is appropriate to use
-      # (e.g., "latest" isn't wrongly pointing to an unstable version, not
-      # picking up the actual latest version, etc.). The strategy can only be
-      # 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.).
+      # The default regex identifies versions like `1.2.3`/`v1.2.3` in the
+      # release's tag name. 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. `1.2.3d`, `1.2.3-4`, etc.).
       #
       # @api public
       class GithubLatest
@@ -50,7 +45,7 @@ class GithubLatest
         # 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
 
         # Whether the strategy can be applied to the provided URL.
@@ -83,9 +78,9 @@ def self.generate_input_values(url)
           values
         end
 
-        # Uses the regex to match release information in content or, if a block is
-        # provided, passes the page content to the block to handle matching.
-        # With either approach, an array of unique matches is returned.
+        # Uses a regex to match the version from release JSON or, if a block is
+        # provided, passes the JSON to the block to handle matching. With
+        # either approach, an array of unique matches is returned.
         #
         # @param content [Array] list of releases
         # @param regex [Regexp] a regex used for matching versions in the content
@@ -119,8 +114,8 @@ def self.versions_from_content(content, regex, &block)
           end.compact.uniq
         end
 
-        # Generates a URL and regex (if one isn't provided) and passes them
-        # to {PageMatch.find_versions} to identify versions in the content.
+        # Generates the GitHub API URL for the repository's "latest" release
+        # 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