Improve documentation comments for Livecheck DSL

Library/Homebrew/livecheck.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
-# Livecheck can be used to check for newer versions of the software.
-# The livecheck DSL specified in the formula is evaluated the methods
-# of this class, which set the instance variables accordingly. The
-# information is used by brew livecheck when checking for newer versions
-# of the software.
+# The `Livecheck` class implements the DSL methods used in a formula's
+# `livecheck` block and stores related instance variables. Most of these methods
+# also return the related instance variable when no argument is provided.
+#
+# This information is used by the `brew livecheck` command to control its
+# behavior.
 class Livecheck
-  # The reason for skipping livecheck for the formula.
-  # e.g. `Not maintained`
+  # A very brief description of why the formula is skipped (e.g., `No longer
+  # developed or maintained`).
+  # @return [String, nil]
   attr_reader :skip_msg
 
   def initialize(formula)
@@ -19,8 +21,10 @@ class Livecheck
     @url = nil
   end
 
-  # Sets the regex instance variable to the argument given, returns the
-  # regex instance variable when no argument is given.
+  # Sets the `@regex` instance variable to the provided `Regexp` or returns the
+  # `@regex` instance variable when no argument is provided.
+  # @param pattern [Regexp] regex to use for matching versions in content
+  # @return [Regexp, nil]
   def regex(pattern = nil)
     case pattern
     when nil
@@ -32,10 +36,12 @@ class Livecheck
     end
   end
 
-  # Sets the skip instance variable to true, indicating that livecheck
-  # must be skipped for the formula. If an argument is given and present,
-  # its value is assigned to the skip_msg instance variable, else nil is
-  # assigned.
+  # Sets the `@skip` instance variable to `true` and sets the `@skip_msg`
+  # instance variable if a `String` is provided. `@skip` is used to indicate
+  # that the formula should be skipped and the `skip_msg` very briefly describes
+  # why the formula is skipped (e.g., `No longer developed or maintained`).
+  # @param skip_msg [String] string describing why the formula is skipped
+  # @return [Boolean]
   def skip(skip_msg = nil)
     if skip_msg.is_a?(String)
       @skip_msg = skip_msg
@@ -46,16 +52,17 @@ class Livecheck
     @skip = true
   end
 
-  # Should livecheck be skipped for the formula?
+  # Should `livecheck` skip this formula?
   def skip?
     @skip
   end
 
-  # Sets the strategy instance variable to the provided symbol or returns the
-  # strategy instance variable when no argument is provided. The strategy
+  # Sets the `@strategy` instance variable to the provided `Symbol` or returns
+  # the `@strategy` instance variable when no argument is provided. The strategy
   # symbols use snake case (e.g., `:page_match`) and correspond to the strategy
   # file name.
   # @param symbol [Symbol] symbol for the desired strategy
+  # @return [Symbol, nil]
   def strategy(symbol = nil)
     case symbol
     when nil
@@ -67,8 +74,12 @@ class Livecheck
     end
   end
 
-  # Sets the url instance variable to the argument given, returns the url
-  # instance variable when no argument is given.
+  # Sets the `@url` instance variable to the provided argument or returns the
+  # `@url` instance variable when no argument is provided. The argument can be
+  # a `String` (a URL) or a supported `Symbol` corresponding to a URL in the
+  # formula (e.g., `:stable`, `:homepage`, or `:head`).
+  # @param val [String, Symbol] URL to check for version information
+  # @return [String, nil]
   def url(val = nil)
     @url = case val
     when nil
@@ -84,7 +95,8 @@ class Livecheck
     end
   end
 
-  # Returns a Hash of all instance variable values.
+  # Returns a `Hash` of all instance variable values.
+  # @return [Hash]
   def to_hash
     {
       "regex"    => @regex,