Explicitly mark non-private APIs.

.github/workflows/tests.yml

@@ -61,13 +61,14 @@ jobs:
  - name: Check RuboCop filepaths
  working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/Library/Homebrew
  run: |
- public_apis=$(git grep -l "@api public" -- :^sorbet/ :^vendor/ | wc -l | tr -d ' ')
- rubocop_docs=$(yq '.Style/Documentation.Include' .rubocop.yml | wc -l | tr -d ' ')
- if [[ public_apis -ne rubocop_docs ]]
- then
- echo "All public Homebrew APIs should be included in the Style/Documentation RuboCop."
- echo "There were ${public_apis} '@api public' lines but ${rubocop_docs} filepaths for the 'Style/Documentation' RuboCop."
- echo "Add or remove the filepaths from Library/Homebrew/.rubocop.yml as appropriate."
+ public_apis="$(git grep -l "@api public" -- :^sorbet/ :^vendor/ | sort)"
+ rubocop_docs="$(yq '.Style/Documentation.Include[]' .rubocop.yml | sort)"
+
+ if [[ "${public_apis}" != "${rubocop_docs}" ]]; then
+ echo "All public Homebrew APIs should be included in the \`Style/Documentation\` RuboCop."
+ echo "Add/remove the following paths from \`Library/Homebrew/.rubocop.yml\` as appropriate:"
+ echo "${public_apis} ${rubocop_docs}" | tr ' ' '\n' | sort | uniq -u
+
  exit 1
  fi
 

Library/Homebrew/.rubocop.yml

@@ -64,6 +64,7 @@ Style/Documentation:
  - utils/shebang.rb
  - utils/string_inreplace_extension.rb
  - version.rb
+ - tap.rb
 
 Style/DocumentationMethod:
  Include:

Library/Homebrew/cask/cask.rb

@@ -20,7 +20,17 @@ class Cask
  extend APIHashable
  include Metadata
 
- attr_reader :token, :sourcefile_path, :source, :config, :default_config, :loader
+ # The token of this {Cask}.
+ #
+ # @api internal
+ attr_reader :token
+
+ # The configuration of this {Cask}.
+ #
+ # @api internal
+ attr_reader :config
+
+ attr_reader :sourcefile_path, :source, :default_config, :loader
  attr_accessor :download, :allow_reassignment
 
  attr_predicate :loaded_from_api?
@@ -124,13 +134,21 @@ def timestamped_versions(caskroom_path: self.caskroom_path)
  .map { |p| p.split.map(&:to_s) }
  end
 
- def full_name
+ # The fully-qualified token of this {Cask}.
+ #
+ # @api internal
+ def full_token
  return token if tap.nil?
  return token if tap.core_cask_tap?
 
  "#{tap.name}/#{token}"
  end
 
+ # Alias for {#full_token}.
+ #
+ # @api internal
+ def full_name = full_token
+
  sig { returns(T::Boolean) }
  def installed?
  installed_caskfile&.exist? || false
@@ -226,6 +244,9 @@ def caskroom_path
  @caskroom_path ||= Caskroom.path.join(token)
  end
 
+ # Check if the installed cask is outdated.
+ #
+ # @api internal
  def outdated?(greedy: false, greedy_latest: false, greedy_auto_updates: false)
  !outdated_version(greedy:, greedy_latest:,
  greedy_auto_updates:).nil?
@@ -304,9 +325,10 @@ def populate_from_api!(json_cask)
  @ruby_source_checksum = { sha256: ruby_source_sha256 }
  end
 
- def to_s
- @token
- end
+ # Alias for {#token}.
+ #
+ # @api internal
+ def to_s = token
 
  def inspect
  "#<Cask #{token}#{sourcefile_path&.to_s&.prepend(" ")}>"

Library/Homebrew/cask/caskroom.rb

@@ -6,7 +6,7 @@
 module Cask
  # Helper functions for interacting with the `Caskroom` directory.
  #
- # @api private
+ # @api internal
  module Caskroom
  sig { returns(Pathname) }
  def self.path
@@ -50,6 +50,9 @@ def self.ensure_caskroom_exists
  SystemCommand.run("/usr/bin/chgrp", args: ["admin", path], sudo:)
  end
 
+ # Get all installed casks.
+ #
+ # @api internal
  sig { params(config: T.nilable(Config)).returns(T::Array[Cask]) }
  def self.casks(config: nil)
  tokens.sort.filter_map do |token|

Library/Homebrew/cask/config.rb

@@ -10,7 +10,7 @@
 module Cask
  # Configuration for installing casks.
  #
- # @api private
+ # @api internal
  class Config
  DEFAULT_DIRS = {
  appdir: "/Applications",
@@ -88,6 +88,9 @@ def self.canonicalize(config)
  end
  end
 
+ # Get the explicit configuration.
+ #
+ # @api internal
  sig { returns(T::Hash[Symbol, T.any(String, Pathname, T::Array[String])]) }
  attr_accessor :explicit
 
@@ -184,6 +187,11 @@ def merge(other)
  self.class.new(explicit: other.explicit.merge(explicit))
  end
 
+ # Get explicit configuration as a string.
+ #
+ # @api internal
+ #
+ # TODO: This is only used by `homebrew/bundle`, so move it there.
  sig { returns(String) }
  def explicit_s
  explicit.map do |key, value|

Library/Homebrew/development_tools.rb

@@ -83,6 +83,9 @@ def llvm_clang_build_version
  end
  end
 
+ # Get the GCC version.
+ #
+ # @api internal
  sig { params(cc: String).returns(Version) }
  def gcc_version(cc)
  (@gcc_version ||= {}).fetch(cc) do

Library/Homebrew/env_config.rb

@@ -6,7 +6,7 @@
 module Homebrew
  # Helper module for querying Homebrew-specific environment variables.
  #
- # @api private
+ # @api internal
  module EnvConfig
  module_function
 

Library/Homebrew/exceptions.rb

@@ -5,6 +5,8 @@
 require "utils"
 
 # Raised when a command is used wrong.
+#
+# @api internal
 class UsageError < RuntimeError
  attr_reader :reason
 
@@ -133,6 +135,8 @@ def to_s
 end
 
 # Raised when a formula is not available.
+#
+# @api internal
 class FormulaUnavailableError < FormulaOrCaskUnavailableError
  attr_accessor :dependent
 

Library/Homebrew/extend/kernel.rb

@@ -58,31 +58,42 @@ def oh1(title, truncate: :auto)
  puts oh1_title(title, truncate:)
  end
 
- # Print a message prefixed with "Warning" (do this rarely).
+ # Print a warning message.
+ #
+ # @api public
  def opoo(message)
  Tty.with($stderr) do |stderr|
  stderr.puts Formatter.warning(message, label: "Warning")
  end
  end
 
- # Print a message prefixed with "Error".
+ # Print an error message.
+ #
+ # @api public
  def onoe(message)
  Tty.with($stderr) do |stderr|
  stderr.puts Formatter.error(message, label: "Error")
  end
  end
 
+ # Print an error message and fail at the end of the program.
+ #
+ # @api public
  def ofail(error)
  onoe error
  Homebrew.failed = true
  end
 
+ # Print an error message and fail immediately.
+ #
+ # @api public
  sig { params(error: T.any(String, Exception)).returns(T.noreturn) }
  def odie(error)
  onoe error
  exit 1
  end
 
+ # Output a deprecation warning/error message.
  def odeprecated(method, replacement = nil,
  disable: false,
  disable_on: nil,
@@ -254,6 +265,9 @@ def quiet_system(cmd, *args)
  end
  end
 
+ # Find a command.
+ #
+ # @api public
  def which(cmd, path = ENV.fetch("PATH"))
  PATH.new(path).each do |p|
  begin