Merge pull request #17157 from reitermarkus/docs-inspect-to_s

Hide `#inspect` and `#to_s` in docs.

Library/Homebrew/.rubocop.yml

@@ -24,6 +24,7 @@ Style/Documentation:
   AllowedConstants:
     - Homebrew
   Include:
+    - cask/cask.rb
     - cask/dsl.rb
     - cask/dsl/version.rb
     - cask/url.rb

Library/Homebrew/PATH.rb

@@ -61,7 +61,10 @@ class PATH
   def to_str
     @paths.join(File::PATH_SEPARATOR)
   end
-  alias to_s to_str
+
+  # @!visibility private
+  sig { returns(String) }
+  def to_s = to_str
 
   sig { params(other: T.untyped).returns(T::Boolean) }
   def ==(other)

Library/Homebrew/cask/artifact/abstract_artifact.rb

@@ -149,6 +149,7 @@ module Cask
         cask.config
       end
 
+      # @!visibility private
       sig { returns(String) }
       def to_s
         "#{summarize} (#{self.class.english_name})"

Library/Homebrew/cask/cask.rb

@@ -325,11 +325,13 @@ module Cask
       @ruby_source_checksum = { sha256: ruby_source_sha256 }
     end
 
-    # Alias for {#token}.
+    # @api public
-    #
+    # @!visibility private
-    # @api internal
+    sig { returns(String) }
     def to_s = token
 
+    # @!visibility private
+    sig { returns(String) }
     def inspect
       "#<Cask #{token}#{sourcefile_path&.to_s&.prepend(" ")}>"
     end

Library/Homebrew/cask/dsl/caveats.rb

@@ -39,6 +39,8 @@ module Cask
 
       private_class_method :caveat
 
+      # @!visibility private
+      sig { returns(String) }
       def to_s
         (@custom_caveats + @built_in_caveats.values).join("\n")
       end

Library/Homebrew/cask/dsl/container.rb

@@ -29,9 +29,9 @@ module Cask
         pairs.to_yaml
       end
 
-      def to_s
+      # @!visibility private
-        pairs.inspect
+      sig { returns(String) }
-      end
+      def to_s = pairs.inspect
     end
   end
 end

Library/Homebrew/cask/exceptions.rb

@@ -17,6 +17,7 @@ module Cask
       @errors = errors
     end
 
+    # @!visibility private
     sig { returns(String) }
     def to_s
       <<~EOS
@@ -48,6 +49,7 @@ module Cask
   #
   # @api private
   class CaskNotInstalledError < AbstractCaskErrorWithToken
+    # @!visibility private
     sig { returns(String) }
     def to_s
       "Cask '#{token}' is not installed."
@@ -65,6 +67,7 @@ module Cask
       @message = message
     end
 
+    # @!visibility private
     sig { returns(String) }
     def to_s
       "Cask '#{token}' has been #{message}"
@@ -82,6 +85,7 @@ module Cask
       @conflicting_cask = conflicting_cask
     end
 
+    # @!visibility private
     sig { returns(String) }
     def to_s
       "Cask '#{token}' conflicts with '#{conflicting_cask}'."
@@ -92,6 +96,7 @@ module Cask
   #
   # @api private
   class CaskUnavailableError < AbstractCaskErrorWithToken
+    # @!visibility private
     sig { returns(String) }
     def to_s
       "Cask '#{token}' is unavailable#{reason.empty? ? "." : ": #{reason}"}"
@@ -102,6 +107,7 @@ module Cask
   #
   # @api private
   class CaskUnreadableError < CaskUnavailableError
+    # @!visibility private
     sig { returns(String) }
     def to_s
       "Cask '#{token}' is unreadable#{reason.empty? ? "." : ": #{reason}"}"
@@ -119,6 +125,7 @@ module Cask
       @tap = tap
     end
 
+    # @!visibility private
     sig { returns(String) }
     def to_s
       s = super
@@ -157,6 +164,7 @@ module Cask
   #
   # @api private
   class CaskAlreadyCreatedError < AbstractCaskErrorWithToken
+    # @!visibility private
     sig { returns(String) }
     def to_s
       %Q(Cask '#{token}' already exists. Run #{Formatter.identifier("brew edit --cask #{token}")} to edit it.)
@@ -167,6 +175,7 @@ module Cask
   #
   # @api private
   class CaskCyclicDependencyError < AbstractCaskErrorWithToken
+    # @!visibility private
     sig { returns(String) }
     def to_s
       "Cask '#{token}' includes cyclic dependencies on other Casks#{reason.empty? ? "." : ": #{reason}"}"
@@ -177,6 +186,7 @@ module Cask
   #
   # @api private
   class CaskSelfReferencingDependencyError < CaskCyclicDependencyError
+    # @!visibility private
     sig { returns(String) }
     def to_s
       "Cask '#{token}' depends on itself."
@@ -187,6 +197,7 @@ module Cask
   #
   # @api private
   class CaskUnspecifiedError < CaskError
+    # @!visibility private
     sig { returns(String) }
     def to_s
       "This command requires a Cask token."
@@ -197,6 +208,7 @@ module Cask
   #
   # @api private
   class CaskInvalidError < AbstractCaskErrorWithToken
+    # @!visibility private
     sig { returns(String) }
     def to_s
       "Cask '#{token}' definition is invalid#{reason.empty? ? "." : ": #{reason}"}"
@@ -225,6 +237,7 @@ module Cask
       @reason = reason
     end
 
+    # @!visibility private
     sig { returns(String) }
     def to_s
       s = +"Failed to quarantine #{path}."
@@ -243,6 +256,7 @@ module Cask
   #
   # @api private
   class CaskQuarantinePropagationError < CaskQuarantineError
+    # @!visibility private
     sig { returns(String) }
     def to_s
       s = +"Failed to quarantine one or more files within #{path}."
@@ -261,6 +275,7 @@ module Cask
   #
   # @api private
   class CaskQuarantineReleaseError < CaskQuarantineError
+    # @!visibility private
     sig { returns(String) }
     def to_s
       s = +"Failed to release #{path} from quarantine."

Library/Homebrew/compilers.rb

@@ -68,6 +68,8 @@ class CompilerFailure
     type == compiler.type && version_matched
   end
 
+  # @!visibility private
+  sig { returns(String) }
   def inspect
     "#<#{self.class.name}: #{type} #{version}>"
   end

Library/Homebrew/cxxstdlib.rb

@@ -22,6 +22,7 @@ class CxxStdlib
     type.to_s.gsub(/cxx$/, "c++")
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: #{compiler} #{type}>"

Library/Homebrew/dependencies.rb

@@ -37,6 +37,7 @@ class Dependencies < SimpleDelegator
     self.class.new(*__getobj__.reject { |dep| dep.uses_from_macos? && dep.use_macos_install? })
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: #{__getobj__}>"
@@ -65,6 +66,7 @@ class Requirements < SimpleDelegator
     self
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: {#{__getobj__.to_a.join(", ")}}>"

Library/Homebrew/dependency.rb

@@ -11,7 +11,11 @@ class Dependency
   include Dependable
   extend Cachable
 
-  attr_reader :name, :tap
+  sig { returns(String) }
+  attr_reader :name
+
+  sig { returns(T.nilable(Tap)) }
+  attr_reader :tap
 
   def initialize(name, tags = [])
     raise ArgumentError, "Dependency must have a name!" unless name
@@ -24,9 +28,9 @@ class Dependency
     @tap, = tap_with_name
   end
 
-  def to_s
+  # @!visibility private
-    name
+  sig { returns(String) }
-  end
+  def to_s = name
 
   def ==(other)
     instance_of?(other.class) && name == other.name && tags == other.tags
@@ -96,6 +100,7 @@ class Dependency
     false
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: #{name.inspect} #{tags.inspect}>"
@@ -279,6 +284,7 @@ class UsesFromMacOSDependency < Dependency
     self.class.new(formula.full_name.to_s, tags, bounds:)
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: #{name.inspect} #{tags.inspect} #{bounds.inspect}>"

Library/Homebrew/exceptions.rb

@@ -16,6 +16,7 @@ class UsageError < RuntimeError
     @reason = reason
   end
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     s = "Invalid usage"
@@ -110,6 +111,7 @@ class FormulaOrCaskUnavailableError < RuntimeError
     "Did you mean #{similar_formula_names.to_sentence two_words_connector: " or ", last_word_connector: " or "}?"
   end
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     s = "No available formula or cask with the name \"#{name}\". #{did_you_mean}".strip
@@ -129,6 +131,7 @@ class TapFormulaOrCaskUnavailableError < FormulaOrCaskUnavailableError
     @tap = tap
   end
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     s = super
@@ -148,6 +151,7 @@ class FormulaUnavailableError < FormulaOrCaskUnavailableError
     " (dependency of #{dependent})" if dependent && dependent != name
   end
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     "No available formula with the name \"#{name}\"#{dependent_s}. #{did_you_mean}".strip
@@ -160,6 +164,8 @@ end
 module FormulaClassUnavailableErrorModule
   attr_reader :path, :class_name, :class_list
 
+  # @!visibility private
+  sig { returns(String) }
   def to_s
     s = super
     s += "\nIn formula file: #{path}"
@@ -204,6 +210,7 @@ end
 module FormulaUnreadableErrorModule
   attr_reader :formula_error
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     "#{name}: " + formula_error.to_s
@@ -232,6 +239,8 @@ class TapFormulaUnavailableError < FormulaUnavailableError
     super "#{tap}/#{name}"
   end
 
+  # @!visibility private
+  sig { returns(String) }
   def to_s
     s = super
     s += "\nPlease tap it and then try again: brew tap #{tap}" unless tap.installed?

Library/Homebrew/formula.rb

@@ -1731,11 +1731,12 @@ class Formula
     [name, *oldnames, *aliases].compact
   end
 
-  def to_s
+  # @api public
-    name
+  # @!visibility private
-  end
+  sig { returns(String) }
+  def to_s = name
 
-  # @private
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<Formula #{name} (#{active_spec_sym}) #{path}>"

Library/Homebrew/formula_support.rb

@@ -37,6 +37,8 @@ class KegOnlyReason
     !by_macos?
   end
 
+  # @!visibility private
+  sig { returns(String) }
   def to_s
     return @explanation unless @explanation.empty?
 

Library/Homebrew/formula_text_auditor.rb

@@ -27,6 +27,8 @@ module Homebrew
       @text.include? string
     end
 
+    # @!visibility private
+    sig { returns(String) }
     def to_s
       @text
     end

Library/Homebrew/git_repository.rb

@@ -107,10 +107,9 @@ class GitRepository
     popen_git("log", "-1", "--pretty=%B", commit, "--", safe:, err: :out)&.strip
   end
 
+  # @!visibility private
   sig { returns(String) }
-  def to_s
+  def to_s = pathname.to_s
-    pathname.to_s
-  end
 
   private
 

Library/Homebrew/keg.rb

@@ -50,6 +50,7 @@ class Keg
       EOS
     end
 
+    # @!visibility private
     sig { returns(String) }
     def to_s
       s = []
@@ -68,6 +69,7 @@ class Keg
 
   # Error for when a directory is not writable.
   class DirectoryNotWritableError < LinkError
+    # @!visibility private
     sig { returns(String) }
     def to_s
       <<~EOS
@@ -155,7 +157,7 @@ class Keg
   extend Forwardable
 
   def_delegators :path,
-                 :to_s, :hash, :abv, :disk_usage, :file_count, :directory?, :exist?, :/,
+                 :to_path, :hash, :abv, :disk_usage, :file_count, :directory?, :exist?, :/,
                  :join, :rename, :find
 
   def initialize(path)
@@ -175,8 +177,11 @@ class Keg
     path.parent
   end
 
-  alias to_path to_s
+  # @!visibility private
+  sig { returns(String) }
+  def to_s = path.to_s
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}:#{path}>"

Library/Homebrew/locale.rb

@@ -108,6 +108,7 @@ class Locale
       locale_groups.find { |locales| locales.any? { |locale| include?(locale) } }
   end
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     [@language, @script, @region].compact.join("-")

Library/Homebrew/mktemp.rb

@@ -38,6 +38,7 @@ class Mktemp
     @quiet = true
   end
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     "[Mktemp: #{tmpdir} retain=#{@retain} quiet=#{@quiet}]"

Library/Homebrew/options.rb

@@ -13,9 +13,9 @@ class Option
     @description = description
   end
 
-  def to_s
+  # @!visibility private
-    flag
+  sig { returns(String) }
-  end
+  def to_s = flag
 
   def <=>(other)
     return unless other.is_a?(Option)
@@ -32,6 +32,7 @@ class Option
     name.hash
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: #{flag.inspect}>"
@@ -139,11 +140,13 @@ class Options
 
   alias to_ary to_a
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     @options.map(&:to_s).join(" ")
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: #{to_a.inspect}>"

Library/Homebrew/patch.rb

@@ -55,6 +55,7 @@ class EmbeddedPatch
     Utils.safe_popen_write("patch", *args) { |p| p.write(data) }
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: #{strip.inspect}>"
@@ -160,6 +161,7 @@ class ExternalPatch
     raise BuildError.new(f, cmd, args, ENV.to_hash)
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: #{strip.inspect} #{url.inspect}>"

Library/Homebrew/pkg_version.rb

@@ -32,14 +32,18 @@ class PkgVersion
     version.head?
   end
 
-  def to_s
+  sig { returns(String) }
+  def to_str
     if revision.positive?
       "#{version}_#{revision}"
     else
       version.to_s
     end
   end
-  alias to_str to_s
+
+  # @!visibility private
+  sig { returns(String) }
+  def to_s = to_str
 
   def <=>(other)
     return unless other.is_a?(PkgVersion)

Library/Homebrew/requirement.rb

@@ -142,6 +142,7 @@ class Requirement
     [self.class, name, tags].hash
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: #{tags.inspect}>"

Library/Homebrew/requirements/arch_requirement.rb

@@ -29,6 +29,8 @@ class ArchRequirement < Requirement
     "The #{@arch} architecture is required for this software."
   end
 
+  # @!visibility private
+  sig { returns(String) }
   def inspect
     "#<#{self.class.name}: arch=#{@arch.to_s.inspect} #{tags.inspect}>"
   end

Library/Homebrew/requirements/macos_requirement.rb

@@ -98,6 +98,7 @@ class MacOSRequirement < Requirement
     [super, comparator, version].hash
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: version#{@comparator}#{@version.to_s.inspect} #{tags.inspect}>"

Library/Homebrew/requirements/xcode_requirement.rb

@@ -50,6 +50,7 @@ class XcodeRequirement < Requirement
     end
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     "#<#{self.class.name}: version>=#{@version.inspect} #{tags.inspect}>"

Library/Homebrew/resource.rb

@@ -294,6 +294,7 @@ class ResourceStageContext
 
   # The {Resource} that is being staged.
   attr_reader :resource
+
   # The {Mktemp} in which {#resource} is staged.
   attr_reader :staging
 
@@ -305,6 +306,7 @@ class ResourceStageContext
     @staging = staging
   end
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     "<#{self.class}: resource=#{resource} staging=#{staging}>"

Library/Homebrew/software_spec.rb

@@ -314,10 +314,13 @@ class Bottle
     end
 
     sig { returns(String) }
-    def to_s
+    def to_str
       "#{name}--#{version}#{extname}"
     end
-    alias to_str to_s
+
+    # @!visibility private
+    sig { returns(String) }
+    def to_s = to_str
 
     sig { returns(String) }
     def json

Library/Homebrew/source_location.rb

@@ -18,6 +18,7 @@ module Homebrew
       @column = column
     end
 
+    # @!visibility private
     sig { returns(String) }
     def to_s
       "#{line}#{column&.to_s&.prepend(":")}"

Library/Homebrew/tab.rb

@@ -403,6 +403,7 @@ class Tab
     tabfile.atomic_write(to_json)
   end
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     s = []

Library/Homebrew/tap.rb

@@ -155,9 +155,9 @@ class Tap
   # @api public
   attr_reader :name
 
-  # Alias for {#name}.
-  #
   # @api public
+  # @!visibility private
+  sig { returns(String) }
   def to_s = name
 
   # The full name of this {Tap}, including the `homebrew-` prefix.

Library/Homebrew/url.rb

@@ -16,6 +16,7 @@ class URL
     @specs.freeze
   end
 
+  # @!visibility private
   sig { returns(String) }
   def to_s
     @url

Library/Homebrew/utils/bottles.rb

@@ -202,6 +202,7 @@ module Utils
         end
       end
 
+      # @!visibility private
       sig { returns(String) }
       def to_s
         to_sym.to_s

Library/Homebrew/utils/github/actions.rb

@@ -73,6 +73,7 @@ module GitHub
         @end_column = Integer(end_column) if end_column
       end
 
+      # @!visibility private
       sig { returns(String) }
       def to_s
         metadata = @type.to_s

Library/Homebrew/utils/pypi.rb

@@ -85,6 +85,7 @@ module PyPI
       ]
     end
 
+    # @!visibility private
     sig { returns(String) }
     def to_s
       if valid_pypi_package?

Library/Homebrew/utils/tty.rb

@@ -100,6 +100,7 @@ module Tty
       end
     end
 
+    # @!visibility private
     sig { returns(String) }
     def to_s
       return "" unless color?

Library/Homebrew/version.rb

@@ -59,6 +59,7 @@ class Version
     sig { abstract.params(other: T.untyped).returns(T.nilable(Integer)) }
     def <=>(other); end
 
+    # @!visibility private
     sig { returns(String) }
     def inspect
       "#<#{self.class.name} #{value.inspect}>"
@@ -80,10 +81,13 @@ class Version
     end
 
     sig { returns(String) }
-    def to_s
+    def to_str
       value.to_s
     end
-    alias to_str to_s
+
+    # @!visibility private
+    sig { returns(String) }
+    def to_s = to_str
 
     sig { returns(T::Boolean) }
     def numeric?
@@ -133,7 +137,8 @@ class Version
     sig { returns(T::Boolean) }
     def blank? = true
 
-    sig { override.returns(String) }
+    # @!visibility private
+    sig { returns(String) }
     def inspect
       "#<#{self.class.name}>"
     end
@@ -702,11 +707,6 @@ class Version
     version.to_i
   end
 
-  sig { returns(String) }
-  def to_s
-    version.to_s
-  end
-
   sig { returns(String) }
   def to_str
     raise NoMethodError, "undefined method `to_str' for #{self.class}:NULL" if null?
@@ -714,6 +714,10 @@ class Version
     T.must(version).to_str
   end
 
+  # @!visibility private
+  sig { returns(String) }
+  def to_s = version.to_s
+
   sig { params(options: T.untyped).returns(String) }
   def to_json(*options)
     version.to_json(*options)
@@ -726,6 +730,7 @@ class Version
     super
   end
 
+  # @!visibility private
   sig { returns(String) }
   def inspect
     return "#<Version::NULL>" if null?