From dddfbf80fc283ca1e849a242db285f44a6919b9c Mon Sep 17 00:00:00 2001 From: EricFromCanada Date: Thu, 5 Nov 2020 15:19:56 -0500 Subject: [PATCH] apidoc: add/update yard tags --- Library/Homebrew/bintray.rb | 5 +-- Library/Homebrew/cask/artifact/colorpicker.rb | 6 ++-- Library/Homebrew/dev-cmd/audit.rb | 2 +- Library/Homebrew/diagnostic.rb | 4 +-- Library/Homebrew/extend/ENV/shared.rb | 3 +- Library/Homebrew/extend/pathname.rb | 2 +- Library/Homebrew/formula.rb | 34 ++++++++++--------- Library/Homebrew/formulary.rb | 12 ++++--- Library/Homebrew/keg.rb | 2 +- Library/Homebrew/software_spec.rb | 2 +- Library/Homebrew/utils.rb | 6 ++-- Library/Homebrew/version.rb | 3 +- 12 files changed, 44 insertions(+), 37 deletions(-) diff --git a/Library/Homebrew/bintray.rb b/Library/Homebrew/bintray.rb index 06093d11b2..ea50ed3479 100644 --- a/Library/Homebrew/bintray.rb +++ b/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 diff --git a/Library/Homebrew/cask/artifact/colorpicker.rb b/Library/Homebrew/cask/artifact/colorpicker.rb index 545389369c..3743b70b21 100644 --- a/Library/Homebrew/cask/artifact/colorpicker.rb +++ b/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 diff --git a/Library/Homebrew/dev-cmd/audit.rb b/Library/Homebrew/dev-cmd/audit.rb index edd6de3e3a..12661d6a9b 100644 --- a/Library/Homebrew/dev-cmd/audit.rb +++ b/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 diff --git a/Library/Homebrew/diagnostic.rb b/Library/Homebrew/diagnostic.rb index 1fec6c0ae3..61ea6f24dd 100644 --- a/Library/Homebrew/diagnostic.rb +++ b/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[ diff --git a/Library/Homebrew/extend/ENV/shared.rb b/Library/Homebrew/extend/ENV/shared.rb index 6ce7864e6a..f01db9dc85 100644 --- a/Library/Homebrew/extend/ENV/shared.rb +++ b/Library/Homebrew/extend/ENV/shared.rb @@ -159,12 +159,13 @@ module SharedEnvExtension end # Outputs the current compiler. - # @return [Symbol] # 
# 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
+ # + # @return [Symbol] def compiler @compiler ||= if (cc = @cc) warn_about_non_apple_gcc(cc) if cc.match?(GNU_GCC_REGEXP) diff --git a/Library/Homebrew/extend/pathname.rb b/Library/Homebrew/extend/pathname.rb index 258bd0af73..0bfbb220fc 100644 --- a/Library/Homebrew/extend/pathname.rb +++ b/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| diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index 430bddfa0d..c9b3a34bd1 100644 --- a/Library/Homebrew/formula.rb +++ b/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. # 
resource("additional_files").stage { bin.install "my/extra/tool" }
- # @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 # 
desc "Example formula"
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 diff --git a/Library/Homebrew/formulary.rb b/Library/Homebrew/formulary.rb index 2421b1d1bb..2c3689f9a6 100644 --- a/Library/Homebrew/formulary.rb +++ b/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 diff --git a/Library/Homebrew/keg.rb b/Library/Homebrew/keg.rb index f6e121bb03..1036b417ec 100644 --- a/Library/Homebrew/keg.rb +++ b/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) diff --git a/Library/Homebrew/software_spec.rb b/Library/Homebrew/software_spec.rb index 06f419608c..d35d145c55 100644 --- a/Library/Homebrew/software_spec.rb +++ b/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 } diff --git a/Library/Homebrew/utils.rb b/Library/Homebrew/utils.rb index 985a294bec..66ceee8919 100644 --- a/Library/Homebrew/utils.rb +++ b/Library/Homebrew/utils.rb @@ -482,9 +482,9 @@ module Kernel # system "echo $PATH" # end # - # 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 diff --git a/Library/Homebrew/version.rb b/Library/Homebrew/version.rb index 4c22d2f28c..eda386ef35 100644 --- a/Library/Homebrew/version.rb +++ b/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