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 @@ def to_ary
  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 @@ def config
  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 @@ def populate_from_api!(json_cask)
  @ruby_source_checksum = { sha256: ruby_source_sha256 }
  end
 
- # Alias for {#token}.
- #
- # @api internal
+ # @api public
+ # @!visibility private
+ 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 @@ def self.caveat(name, &block)
 
  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 @@ def to_yaml
  pairs.to_yaml
  end
 
- def to_s
-  pairs.inspect
- end
+ # @!visibility private
+ sig { returns(String) }
+ def to_s = pairs.inspect
  end
  end
 end

Library/Homebrew/cask/exceptions.rb

@@ -17,6 +17,7 @@ def initialize(errors)
  @errors = errors
  end
 
+ # @!visibility private
  sig { returns(String) }
  def to_s
  <<~EOS
@@ -48,6 +49,7 @@ def initialize(token, reason = nil)
  #
  # @api private
  class CaskNotInstalledError < AbstractCaskErrorWithToken
+ # @!visibility private
  sig { returns(String) }
  def to_s
  "Cask '#{token}' is not installed."
@@ -65,6 +67,7 @@ def initialize(token, message)
  @message = message
  end
 
+ # @!visibility private
  sig { returns(String) }
  def to_s
  "Cask '#{token}' has been #{message}"
@@ -82,6 +85,7 @@ def initialize(token, conflicting_cask)
  @conflicting_cask = conflicting_cask
  end
 
+ # @!visibility private
  sig { returns(String) }
  def to_s
  "Cask '#{token}' conflicts with '#{conflicting_cask}'."
@@ -92,6 +96,7 @@ def to_s
  #
  # @api private
  class CaskUnavailableError < AbstractCaskErrorWithToken
+ # @!visibility private
  sig { returns(String) }
  def to_s
  "Cask '#{token}' is unavailable#{reason.empty? ? "." : ": #{reason}"}"
@@ -102,6 +107,7 @@ def to_s
  #
  # @api private
  class CaskUnreadableError < CaskUnavailableError
+ # @!visibility private
  sig { returns(String) }
  def to_s
  "Cask '#{token}' is unreadable#{reason.empty? ? "." : ": #{reason}"}"
@@ -119,6 +125,7 @@ def initialize(tap, token)
  @tap = tap
  end
 
+ # @!visibility private
  sig { returns(String) }
  def to_s
  s = super
@@ -157,6 +164,7 @@ def initialize(token, loaders)
  #
  # @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 @@ def to_s
  #
  # @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 @@ def to_s
  #
  # @api private
  class CaskSelfReferencingDependencyError < CaskCyclicDependencyError
+ # @!visibility private
  sig { returns(String) }
  def to_s
  "Cask '#{token}' depends on itself."
@@ -187,6 +197,7 @@ def to_s
  #
  # @api private
  class CaskUnspecifiedError < CaskError
+ # @!visibility private
  sig { returns(String) }
  def to_s
  "This command requires a Cask token."
@@ -197,6 +208,7 @@ def to_s
  #
  # @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 @@ def initialize(path, reason)
  @reason = reason
  end
 
+ # @!visibility private
  sig { returns(String) }
  def to_s
  s = +"Failed to quarantine #{path}."
@@ -243,6 +256,7 @@ def to_s
  #
  # @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 @@ def to_s
  #
  # @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 @@ def fails_with?(compiler)
  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 @@ def type_string
  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 @@ def dup_without_system_deps
  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 @@ def <<(other)
  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 @@ def initialize(name, tags = [])
  @tap, = tap_with_name
  end
 
- def to_s
-  name
- end
+ # @!visibility private
+ sig { returns(String) }
+ def to_s = name
 
  def ==(other)
  instance_of?(other.class) && name == other.name && tags == other.tags
@@ -96,6 +100,7 @@ def uses_from_macos?
  false
  end
 
+ # @!visibility private
  sig { returns(String) }
  def inspect
  "#<#{self.class.name}: #{name.inspect} #{tags.inspect}>"
@@ -279,6 +284,7 @@ def dup_with_formula_name(formula)
  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 @@ def initialize(reason = nil)
  @reason = reason
  end
 
+ # @!visibility private
  sig { returns(String) }
  def to_s
  s = "Invalid usage"
@@ -110,6 +111,7 @@ def did_you_mean
  "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 @@ def initialize(tap, name)
  @tap = tap
  end
 
+ # @!visibility private
  sig { returns(String) }
  def to_s
  s = super
@@ -148,6 +151,7 @@ def dependent_s
  " (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 @@ def to_s
 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 @@ def initialize(name, path, class_name, class_list)
 module FormulaUnreadableErrorModule
  attr_reader :formula_error
 
+ # @!visibility private
  sig { returns(String) }
  def to_s
  "#{name}: " + formula_error.to_s
@@ -232,6 +239,8 @@ def initialize(tap, name)
  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 @@ def possible_names
  [name, *oldnames, *aliases].compact
  end
 
- def to_s
- name
- end
+ # @api public
+ # @!visibility private
+ 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 @@ def applicable?
  !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 @@ def include?(string)
  @text.include? string
  end
 
+ # @!visibility private
+ sig { returns(String) }
  def to_s
  @text
  end

Library/Homebrew/git_repository.rb

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