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