Merge pull request #20383 from Homebrew/rubydoc-fixes

RubyDoc output improvements

Author: MikeMcQuaid

Library/Homebrew/build_options.rb

@@ -85,7 +85,7 @@ def head?
   # ### Example
   #
   # ```ruby
-  # args << "--some-beta" if build.head?
+  # args << "--some-feature" if build.stable?
   # ```
   def stable?
     !head?

Library/Homebrew/cask/dsl.rb

@@ -561,8 +561,8 @@ def livecheckable?
 
     # Excludes the cask from autobump list.
     #
-    # TODO: limit this method to the official taps only (f.e. raise
-    # an error if `!tap.official?`)
+    # TODO: limit this method to the official taps only
+    #       (e.g. raise an error if `!tap.official?`)
     #
     # @api public
     sig { params(because: T.any(String, Symbol)).void }

Library/Homebrew/cask/url.rb

@@ -42,32 +42,24 @@ class DSL
       extend Forwardable
       def_delegators :uri, :path, :scheme, :to_s
 
+      # Creates a `url` stanza.
+      #
+      # @api public
       sig {
         params(
           uri:        T.any(URI::Generic, String),
-          # @api public
           verified:   T.nilable(String),
-          # @api public
           using:      T.any(T::Class[AbstractDownloadStrategy], Symbol, NilClass),
-          # @api public
           tag:        T.nilable(String),
-          # @api public
           branch:     T.nilable(String),
-          # @api public
           revisions:  T.nilable(T::Hash[T.any(Symbol, String), String]),
-          # @api public
           revision:   T.nilable(String),
-          # @api public
           trust_cert: T.nilable(T::Boolean),
-          # @api public
           cookies:    T.nilable(T::Hash[String, String]),
           referer:    T.nilable(T.any(URI::Generic, String)),
-          # @api public
           header:     T.nilable(T.any(String, T::Array[String])),
           user_agent: T.nilable(T.any(Symbol, String)),
-          # @api public
           data:       T.nilable(T::Hash[String, String]),
-          # @api public
           only_path:  T.nilable(String),
         ).void
       }

Library/Homebrew/dev-cmd/contributions.rb

@@ -68,10 +68,10 @@ def run
         users = args.user.presence || GitHub.members_by_team("Homebrew", "maintainers").keys
         users.each do |username|
           # TODO: Using the GitHub username to scan the `git log` undercounts some
-          # contributions as people might not always have configured their Git
-          # committer details to match the ones on GitHub.
+          #       contributions as people might not always have configured their Git
+          #       committer details to match the ones on GitHub.
           # TODO: Switch to using the GitHub APIs instead of `git log` if
-          # they ever support trailers.
+          #       they ever support trailers.
           results[username] = scan_repositories(repos, username, from:)
           grand_totals[username] = total(results[username])
 

Library/Homebrew/download_strategy.rb

@@ -663,7 +663,7 @@ def curl(*args, print_stdout: true, **options)
   end
 end
 
-# Strategy for downloading a file using homebrew's curl.
+# Strategy for downloading a file using Homebrew's `curl`.
 #
 # @api public
 class HomebrewCurlDownloadStrategy < CurlDownloadStrategy

Library/Homebrew/extend/kernel.rb

@@ -3,7 +3,7 @@
 
 # Contains shorthand Homebrew utility methods like `ohai`, `opoo`, `odisabled`.
 # TODO: move these out of `Kernel` into `Homebrew::GlobalMethods` and add
-# necessary Sorbet and global Kernel inclusions.
+#       necessary Sorbet and global Kernel inclusions.
 
 module Kernel
   sig { params(env: T.nilable(String)).returns(T::Boolean) }