apidoc: add/update yard tags

Library/Homebrew/bintray.rb

@@ -152,8 +152,9 @@ class Bintray
   end
 
   # Gets the SHA-256 checksum of the specified remote file.
-  # Returns the empty string if the file exists but doesn't have a checksum.
-  # Returns nil if the file doesn't exist.
+  #
+  # @return the empty string if the file exists but doesn't have a checksum.
+  # @return [nil] if the file doesn't exist.
   def remote_checksum(repo:, remote_file:)
     url = "https://dl.bintray.com/#{@bintray_org}/#{repo}/#{remote_file}"
     result = curl_output "--fail", "--silent", "--head", url

Library/Homebrew/cask/artifact/colorpicker.rb

@@ -4,10 +4,10 @@
 require "cask/artifact/moved"
 
 module Cask
-  # Artifact corresponding to the `colorpicker` stanza.
-  #
-  # @api private
   module Artifact
+    # Artifact corresponding to the `colorpicker` stanza.
+    #
+    # @api private
     class Colorpicker < Moved
     end
   end

Library/Homebrew/dev-cmd/audit.rb

@@ -433,7 +433,7 @@ module Homebrew
       end
     end
 
-    # try to remove these, it's not a good user experience
+    # TODO: try to remove these, it's not a good user experience
     VERSIONED_DEPENDENCIES_CONFLICTS_ALLOWLIST = %w[
       agda
       anjuta

Library/Homebrew/diagnostic.rb

@@ -52,7 +52,7 @@ module Homebrew
         @verbose = verbose
       end
 
-      ############# HELPERS
+      ############# @!group HELPERS
       # Finds files in `HOMEBREW_PREFIX` *and* /usr/local.
       # Specify paths relative to a prefix, e.g. "include/foo.h".
       # Sets @found for your convenience.
@@ -78,7 +78,7 @@ module Homebrew
       def add_info(*args)
         ohai(*args) if @verbose
       end
-      ############# END HELPERS
+      ############# @!endgroup END HELPERS
 
       def fatal_preinstall_checks
         %w[

Library/Homebrew/extend/ENV/shared.rb

@@ -159,12 +159,13 @@ module SharedEnvExtension
   end
 
   # Outputs the current compiler.
-  # @return [Symbol]
   # <pre># Do something only for the system clang
   # if ENV.compiler == :clang
   #   # modify CFLAGS CXXFLAGS OBJCFLAGS OBJCXXFLAGS in one go:
   #   ENV.append_to_cflags "-I ./missing/includes"
   # end</pre>
+  #
+  # @return [Symbol]
   def compiler
     @compiler ||= if (cc = @cc)
       warn_about_non_apple_gcc(cc) if cc.match?(GNU_GCC_REGEXP)

Library/Homebrew/extend/pathname.rb

@@ -165,7 +165,7 @@ class Pathname
     open("a", *open_args) { |f| f.puts(content) }
   end
 
-  # NOTE: This always overwrites.
+  # @note This always overwrites.
   def atomic_write(content)
     old_stat = stat if exist?
     File.atomic_write(self) do |file|

Library/Homebrew/formula.rb

@@ -151,6 +151,7 @@ class Formula
   attr_reader :revision
 
   # Used to change version schemes for packages
+  # @see .version_scheme=
   attr_reader :version_scheme
 
   # The current working directory during builds.
@@ -357,34 +358,34 @@ class Formula
   end
 
   # The description of the software.
-  # @method desc
+  # @!method desc
   # @see .desc=
   delegate desc: :"self.class"
 
   # The SPDX ID of the software license.
-  # @method license
+  # @!method license
   # @see .license=
   delegate license: :"self.class"
 
   # The homepage for the software.
-  # @method homepage
+  # @!method homepage
   # @see .homepage=
   delegate homepage: :"self.class"
 
   # The livecheck specification for the software.
-  # @method livecheck
+  # @!method livecheck
   # @see .livecheck=
   delegate livecheck: :"self.class"
 
   # Is a livecheck specification defined for the software?
-  # @method livecheckable?
+  # @!method livecheckable?
   # @see .livecheckable?
   delegate livecheckable?: :"self.class"
 
   # The version for the currently active {SoftwareSpec}.
   # The version is autodetected from the URL and/or tag so only needs to be
   # declared if it cannot be autodetected correctly.
-  # @method version
+  # @!method version
   # @see .version
   delegate version: :active_spec
 
@@ -429,7 +430,7 @@ class Formula
   # Additional downloads can be defined as {#resource}s.
   # {Resource#stage} will create a temporary directory and yield to a block.
   # <pre>resource("additional_files").stage { bin.install "my/extra/tool" }</pre>
-  # @method resource
+  # @!method resource
   delegate resource: :active_spec
 
   # An old name for the formula
@@ -452,7 +453,7 @@ class Formula
   end
 
   # The {Resource}s for the currently active {SoftwareSpec}.
-  # @method resources
+  # @!method resources
   def_delegator :"active_spec.resources", :values, :resources
 
   # The {Dependency}s for the currently active {SoftwareSpec}.
@@ -483,7 +484,7 @@ class Formula
   delegate deprecated_flags: :active_spec
 
   # If a named option is defined for the currently active {SoftwareSpec}.
-  # @method option_defined?
+  # @!method option_defined?
   delegate option_defined?: :active_spec
 
   # All the {.fails_with} for the currently active {SoftwareSpec}.
@@ -1071,6 +1072,7 @@ class Formula
 
   # Rarely, you don't want your library symlinked into the main prefix.
   # See `gettext.rb` for an example.
+  # @see .keg_only
   def keg_only?
     return false unless keg_only_reason
 
@@ -1135,25 +1137,25 @@ class Formula
 
   # Whether this {Formula} is deprecated (i.e. warns on installation).
   # Defaults to false.
-  # @method deprecated?
+  # @!method deprecated?
   # @return [Boolean]
   delegate deprecated?: :"self.class"
 
   # The reason this {Formula} is deprecated.
   # Returns `nil` if no reason is specified or the formula is not deprecated.
-  # @method deprecation_reason
+  # @!method deprecation_reason
   # @return [String, Symbol]
   delegate deprecation_reason: :"self.class"
 
   # Whether this {Formula} is disabled (i.e. cannot be installed).
   # Defaults to false.
-  # @method disabled?
+  # @!method disabled?
   # @return [Boolean]
   delegate disabled?: :"self.class"
 
   # The reason this {Formula} is disabled.
   # Returns `nil` if no reason is specified or the formula is not disabled.
-  # @method disable_reason
+  # @!method disable_reason
   # @return [String, Symbol]
   delegate disable_reason: :"self.class"
 
@@ -2213,7 +2215,7 @@ class Formula
     # @private
     attr_reader :keg_only_reason
 
-    # @!attribute [w]
+    # @!attribute [w] desc
     # A one-line description of the software. Used by users to get an overview
     # of the software and Homebrew maintainers.
     # Shows when running `brew info`.
@@ -2221,7 +2223,7 @@ class Formula
     # <pre>desc "Example formula"</pre>
     attr_rw :desc
 
-    # @!attribute [w]
+    # @!attribute [w] license
     # The SPDX ID of the open-source license that the formula uses.
     # Shows when running `brew info`.
     # Use `:any_of`, `:all_of` or `:with` to describe complex license expressions.
@@ -2776,7 +2778,7 @@ class Formula
     end
 
     # The reason for deprecation of a {Formula}.
-    # Returns `nil` if no reason was provided or the formula is not deprecated.
+    # @return [nil] if no reason was provided or the formula is not deprecated.
     # @return [String, Symbol]
     attr_reader :deprecation_reason
 

Library/Homebrew/formulary.rb

@@ -356,9 +356,10 @@ module Formulary
   # Return a Formula instance for the given rack.
   # It will auto resolve formula's spec when requested spec is nil
   #
-  # The :alias_path option will be used if the formula is found not to be
-  # installed, and discarded if it is installed because the alias_path used
-  # to install the formula will be set instead.
+  # @param spec when nil, will auto resolve the formula's spec.
+  # @param :alias_path will be used if the formula is found not to be
+  #   installed, and discarded if it is installed because the `alias_path` used
+  #   to install the formula will be set instead.
   def self.from_rack(rack, spec = nil, alias_path: nil, force_bottle: false, flags: [])
     kegs = rack.directory? ? rack.subdirs.map { |d| Keg.new(d) } : []
     keg = kegs.find(&:linked?) || kegs.find(&:optlinked?) || kegs.max_by(&:version)
@@ -378,8 +379,9 @@ module Formulary
     false
   end
 
-  # Return a Formula instance for the given keg.
-  # It will auto resolve formula's spec when requested spec is nil
+  # Return a {Formula} instance for the given keg.
+  #
+  # @param spec when nil, will auto resolve the formula's spec.
   def self.from_keg(keg, spec = nil, alias_path: nil, force_bottle: false, flags: [])
     tab = Tab.for_keg(keg)
     tap = tab.tap

Library/Homebrew/keg.rb

@@ -181,7 +181,7 @@ class Keg
     [all_required_kegs.to_a, all_dependents.sort]
   end
 
-  # if path is a file in a keg then this will return the containing Keg object
+  # @param path if this is a file in a keg, returns the containing {Keg} object.
   def self.for(path)
     original_path = path
     if original_path.exist? && (path = original_path.realpath)

Library/Homebrew/software_spec.rb

@@ -216,7 +216,7 @@ class SoftwareSpec
     end
   end
 
-  # TODO
+  # TODO: ?
   def add_legacy_patches(list)
     list = Patch.normalize_legacy_patches(list)
     list.each { |p| p.owner = self }

Library/Homebrew/utils.rb

@@ -482,9 +482,9 @@ module Kernel
   #   system "echo $PATH"
   # end</pre>
   #
-  # Note that this method is *not* thread-safe - other threads
-  # which happen to be scheduled during the block will also
-  # see these environment variables.
+  # @note This method is *not* thread-safe - other threads
+  #   which happen to be scheduled during the block will also
+  #   see these environment variables.
   def with_env(hash)
     old_values = {}
     begin

Library/Homebrew/version.rb

@@ -583,7 +583,8 @@ class Version
   end
 end
 
-# A formula's [HEAD version](https://docs.brew.sh/Formula-Cookbook#unstable-versions-head).
+# A formula's HEAD version.
+# @see https://docs.brew.sh/Formula-Cookbook#unstable-versions-head Unstable versions (head)
 #
 # @api private
 class HeadVersion < Version