Merge pull request #16831 from reitermarkus/docs-private-by-default

Make documentation `@api private` by default.

Library/Homebrew/.rubocop.yml

@@ -28,8 +28,11 @@ Style/Documentation:
     - cask/dsl.rb
     - cask/dsl/version.rb
     - cask/url.rb
+    - development_tools.rb
     - download_strategy.rb
+    - extend/ENV/super.rb
     - extend/kernel.rb
+    - extend/pathname.rb
     - formula.rb
     - formula_assertions.rb
     - formula_free_port.rb

Library/Homebrew/.yardopts

@@ -3,7 +3,7 @@
 --markup markdown
 --no-private
 --plugin sorbet
---load yard/ignore_directives.rb
+--load ./yard/docstring_parser.rb
 --template-path yard/templates
 --exclude sorbet/rbi/gems/
 --exclude test/

Library/Homebrew/Gemfile

@@ -15,6 +15,10 @@ end
 
 # installed gems (should all be require: false)
 # ALL gems that are not vendored should be in a group
+group :doc, optional: true do
+  gem "yard", require: false
+  gem "yard-sorbet", require: false
+end
 group :ast, optional: true do
   gem "rubocop-ast", require: false
 end

Library/Homebrew/Gemfile.lock

@@ -198,6 +198,8 @@ DEPENDENCIES
   stackprof
   tapioca
   warning
+  yard
+  yard-sorbet
 
 RUBY VERSION
    ruby 3.1.4p223

Library/Homebrew/PATH.rb

@@ -2,8 +2,6 @@
 # frozen_string_literal: true
 
 # Representation of a `*PATH` environment variable.
-#
-# @api private
 class PATH
   include Enumerable
   extend Forwardable

Library/Homebrew/api.rb

@@ -9,8 +9,6 @@ require "extend/cachable"
 
 module Homebrew
   # Helper functions for using Homebrew's formulae.brew.sh API.
-  #
-  # @api private
   module API
     extend Cachable
 
@@ -191,7 +189,6 @@ module Homebrew
     end
   end
 
-  # @api private
   sig { params(block: T.proc.returns(T.untyped)).returns(T.untyped) }
   def self.with_no_api_env(&block)
     return yield if Homebrew::EnvConfig.no_install_from_api?
@@ -199,7 +196,6 @@ module Homebrew
     with_env(HOMEBREW_NO_INSTALL_FROM_API: "1", HOMEBREW_AUTOMATICALLY_SET_NO_INSTALL_FROM_API: "1", &block)
   end
 
-  # @api private
   sig { params(condition: T::Boolean, block: T.proc.returns(T.untyped)).returns(T.untyped) }
   def self.with_no_api_env_if_needed(condition, &block)
     return yield unless condition

Library/Homebrew/api/analytics.rb

@@ -4,8 +4,6 @@
 module Homebrew
   module API
     # Helper functions for using the analytics JSON API.
-    #
-    # @api private
     module Analytics
       class << self
         sig { returns(String) }

Library/Homebrew/api/cask.rb

@@ -7,8 +7,6 @@ require "api/download"
 module Homebrew
   module API
     # Helper functions for using the cask JSON API.
-    #
-    # @api private
     module Cask
       extend Cachable
 

Library/Homebrew/api/download.rb

@@ -5,7 +5,6 @@ require "downloadable"
 
 module Homebrew
   module API
-    # @api private
     class DownloadStrategy < CurlDownloadStrategy
       sig { override.returns(Pathname) }
       def symlink_location
@@ -13,7 +12,6 @@ module Homebrew
       end
     end
 
-    # @api private
     class Download < Downloadable
       sig {
         params(

Library/Homebrew/api/formula.rb

@@ -7,8 +7,6 @@ require "api/download"
 module Homebrew
   module API
     # Helper functions for using the formula JSON API.
-    #
-    # @api private
     module Formula
       extend Cachable
 

Library/Homebrew/build.rb

@@ -17,8 +17,6 @@ require "socket"
 require "cmd/install"
 
 # A formula build.
-#
-# @api private
 class Build
   attr_reader :formula, :deps, :reqs, :args
 

Library/Homebrew/build_environment.rb

@@ -2,8 +2,6 @@
 # frozen_string_literal: true
 
 # Settings for the build environment.
-#
-# @api private
 class BuildEnvironment
   sig { params(settings: Symbol).void }
   def initialize(*settings)

Library/Homebrew/build_options.rb

@@ -2,10 +2,7 @@
 # frozen_string_literal: true
 
 # Options for a formula build.
-#
-# @api private
 class BuildOptions
-  # @private
   def initialize(args, options)
     @args = args
     @options = options
@@ -70,12 +67,10 @@ class BuildOptions
     !@args.empty? || !@options.empty?
   end
 
-  # @private
   def used_options
     @options & @args
   end
 
-  # @private
   def unused_options
     @options - @args
   end

Library/Homebrew/bump_version_parser.rb

@@ -3,8 +3,6 @@
 
 module Homebrew
   # Class handling architecture-specific version information.
-  #
-  # @api private
   class BumpVersionParser
     sig { returns(T.nilable(T.any(Version, Cask::DSL::Version))) }
     attr_reader :arm, :general, :intel

Library/Homebrew/bundle_version.rb

@@ -5,8 +5,6 @@ require "system_command"
 
 module Homebrew
   # Representation of a macOS bundle version, commonly found in `Info.plist` files.
-  #
-  # @api private
   class BundleVersion
     include Comparable
 

Library/Homebrew/cask/artifact.rb

@@ -30,8 +30,6 @@ require "cask/artifact/zap"
 
 module Cask
   # Module containing all cask artifact classes.
-  #
-  # @api private
   module Artifact
   end
 end

Library/Homebrew/cask/artifact/abstract_artifact.rb

@@ -7,8 +7,6 @@ require "extend/object/deep_dup"
 module Cask
   module Artifact
     # Abstract superclass for all artifacts.
-    #
-    # @api private
     class AbstractArtifact
       extend T::Helpers
       abstract!

Library/Homebrew/cask/artifact/abstract_flight_block.rb

@@ -6,8 +6,6 @@ require "cask/artifact/abstract_artifact"
 module Cask
   module Artifact
     # Abstract superclass for block artifacts.
-    #
-    # @api private
     class AbstractFlightBlock < AbstractArtifact
       def self.dsl_key
         super.to_s.sub(/_block$/, "").to_sym

Library/Homebrew/cask/artifact/abstract_uninstall.rb

@@ -12,8 +12,6 @@ require "system_command"
 module Cask
   module Artifact
     # Abstract superclass for uninstall artifacts.
-    #
-    # @api private
     class AbstractUninstall < AbstractArtifact
       include SystemCommand::Mixin
 

Library/Homebrew/cask/artifact/app.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `app` stanza.
-    #
-    # @api private
     class App < Moved
     end
   end

Library/Homebrew/cask/artifact/artifact.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Generic artifact corresponding to the `artifact` stanza.
-    #
-    # @api private
     class Artifact < Moved
       sig { returns(String) }
       def self.english_name

Library/Homebrew/cask/artifact/audio_unit_plugin.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `audio_unit_plugin` stanza.
-    #
-    # @api private
     class AudioUnitPlugin < Moved
     end
   end

Library/Homebrew/cask/artifact/binary.rb

@@ -6,8 +6,6 @@ require "cask/artifact/symlinked"
 module Cask
   module Artifact
     # Artifact corresponding to the `binary` stanza.
-    #
-    # @api private
     class Binary < Symlinked
       def link(command: nil, **options)
         super(command:, **options)

Library/Homebrew/cask/artifact/colorpicker.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `colorpicker` stanza.
-    #
-    # @api private
     class Colorpicker < Moved
     end
   end

Library/Homebrew/cask/artifact/dictionary.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `dictionary` stanza.
-    #
-    # @api private
     class Dictionary < Moved
     end
   end

Library/Homebrew/cask/artifact/font.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `font` stanza.
-    #
-    # @api private
     class Font < Moved
     end
   end

Library/Homebrew/cask/artifact/input_method.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `input_method` stanza.
-    #
-    # @api private
     class InputMethod < Moved
     end
   end

Library/Homebrew/cask/artifact/installer.rb

@@ -7,8 +7,6 @@ require "extend/hash/keys"
 module Cask
   module Artifact
     # Artifact corresponding to the `installer` stanza.
-    #
-    # @api private
     class Installer < AbstractArtifact
       VALID_KEYS = Set.new([
         :manual,

Library/Homebrew/cask/artifact/internet_plugin.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `internet_plugin` stanza.
-    #
-    # @api private
     class InternetPlugin < Moved
     end
   end

Library/Homebrew/cask/artifact/keyboard_layout.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `keyboard_layout` stanza.
-    #
-    # @api private
     class KeyboardLayout < Moved
       def install_phase(**options)
         super(**options)

Library/Homebrew/cask/artifact/manpage.rb

@@ -6,8 +6,6 @@ require "cask/artifact/symlinked"
 module Cask
   module Artifact
     # Artifact corresponding to the `manpage` stanza.
-    #
-    # @api private
     class Manpage < Symlinked
       attr_reader :section
 

Library/Homebrew/cask/artifact/mdimporter.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `mdimporter` stanza.
-    #
-    # @api private
     class Mdimporter < Moved
       sig { returns(String) }
       def self.english_name

Library/Homebrew/cask/artifact/moved.rb

@@ -7,8 +7,6 @@ require "cask/quarantine"
 module Cask
   module Artifact
     # Superclass for all artifacts that are installed by moving them to the target location.
-    #
-    # @api private
     class Moved < Relocated
       sig { returns(String) }
       def self.english_description

Library/Homebrew/cask/artifact/pkg.rb

@@ -10,8 +10,6 @@ require "extend/hash/keys"
 module Cask
   module Artifact
     # Artifact corresponding to the `pkg` stanza.
-    #
-    # @api private
     class Pkg < AbstractArtifact
       attr_reader :path, :stanza_options
 

Library/Homebrew/cask/artifact/postflight_block.rb

@@ -6,8 +6,6 @@ require "cask/artifact/abstract_flight_block"
 module Cask
   module Artifact
     # Artifact corresponding to the `postflight` stanza.
-    #
-    # @api private
     class PostflightBlock < AbstractFlightBlock
     end
   end

Library/Homebrew/cask/artifact/preflight_block.rb

@@ -6,8 +6,6 @@ require "cask/artifact/abstract_flight_block"
 module Cask
   module Artifact
     # Artifact corresponding to the `preflight` stanza.
-    #
-    # @api private
     class PreflightBlock < AbstractFlightBlock
     end
   end

Library/Homebrew/cask/artifact/prefpane.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `prefpane` stanza.
-    #
-    # @api private
     class Prefpane < Moved
       sig { returns(String) }
       def self.english_name

Library/Homebrew/cask/artifact/qlplugin.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `qlplugin` stanza.
-    #
-    # @api private
     class Qlplugin < Moved
       sig { returns(String) }
       def self.english_name

Library/Homebrew/cask/artifact/relocated.rb

@@ -7,8 +7,6 @@ require "extend/hash/keys"
 module Cask
   module Artifact
     # Superclass for all artifacts which have a source and a target location.
-    #
-    # @api private
     class Relocated < AbstractArtifact
       def self.from_args(cask, *args)
         source_string, target_hash = args

Library/Homebrew/cask/artifact/screen_saver.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `screen_saver` stanza.
-    #
-    # @api private
     class ScreenSaver < Moved
     end
   end

Library/Homebrew/cask/artifact/service.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `service` stanza.
-    #
-    # @api private
     class Service < Moved
     end
   end

Library/Homebrew/cask/artifact/stage_only.rb

@@ -6,8 +6,6 @@ require "cask/artifact/abstract_artifact"
 module Cask
   module Artifact
     # Artifact corresponding to the `stage_only` stanza.
-    #
-    # @api private
     class StageOnly < AbstractArtifact
       def self.from_args(cask, *args, **kwargs)
         if (args != [true] && args != ["true"]) || kwargs.present?

Library/Homebrew/cask/artifact/suite.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `suite` stanza.
-    #
-    # @api private
     class Suite < Moved
       sig { returns(String) }
       def self.english_name

Library/Homebrew/cask/artifact/symlinked.rb

@@ -6,8 +6,6 @@ require "cask/artifact/relocated"
 module Cask
   module Artifact
     # Superclass for all artifacts which are installed by symlinking them to the target location.
-    #
-    # @api private
     class Symlinked < Relocated
       sig { returns(String) }
       def self.link_type_english_name

Library/Homebrew/cask/artifact/uninstall.rb

@@ -8,8 +8,6 @@ UPGRADE_REINSTALL_SKIP_DIRECTIVES = [:quit, :signal].freeze
 module Cask
   module Artifact
     # Artifact corresponding to the `uninstall` stanza.
-    #
-    # @api private
     class Uninstall < AbstractUninstall
       def uninstall_phase(upgrade: false, reinstall: false, **options)
         filtered_directives = ORDERED_DIRECTIVES.filter do |directive_sym|

Library/Homebrew/cask/artifact/vst3_plugin.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `vst3_plugin` stanza.
-    #
-    # @api private
     class Vst3Plugin < Moved
       sig { returns(String) }
       def self.english_name

Library/Homebrew/cask/artifact/vst_plugin.rb

@@ -6,8 +6,6 @@ require "cask/artifact/moved"
 module Cask
   module Artifact
     # Artifact corresponding to the `vst_plugin` stanza.
-    #
-    # @api private
     class VstPlugin < Moved
       sig { returns(String) }
       def self.english_name

Library/Homebrew/cask/artifact/zap.rb

@@ -6,8 +6,6 @@ require "cask/artifact/abstract_uninstall"
 module Cask
   module Artifact
     # Artifact corresponding to the `zap` stanza.
-    #
-    # @api private
     class Zap < AbstractUninstall
       def zap_phase(**options)
         dispatch_uninstall_directives(**options)

Library/Homebrew/cask/artifact_set.rb

@@ -5,8 +5,6 @@ require "set"
 
 module Cask
   # Sorted set containing all cask artifacts.
-  #
-  # @api private
   class ArtifactSet < ::Set
     def each(&block)
       return enum_for(T.must(__method__)) { size } unless block

Library/Homebrew/cask/audit.rb

@@ -14,8 +14,6 @@ require "utils/shared_audits"
 
 module Cask
   # Audit a cask for various problems.
-  #
-  # @api private
   class Audit
     include SystemCommand::Mixin
     include ::Utils::Curl

Library/Homebrew/cask/auditor.rb

@@ -5,8 +5,6 @@ require "cask/audit"
 
 module Cask
   # Helper class for auditing all available languages of a cask.
-  #
-  # @api private
   class Auditor
     def self.audit(cask, **options)
       new(cask, **options).audit

Library/Homebrew/cask/cache.rb

@@ -3,8 +3,6 @@
 
 module Cask
   # Helper functions for the cask cache.
-  #
-  # @api private
   module Cache
     sig { returns(Pathname) }
     def self.path

Library/Homebrew/cask/cask.rb

@@ -12,8 +12,6 @@ require "extend/api_hashable"
 
 module Cask
   # An instance of a cask.
-  #
-  # @api private
   class Cask
     extend Forwardable
     extend Attrable
@@ -35,7 +33,6 @@ module Cask
 
     attr_predicate :loaded_from_api?
 
-    # @api private
     def self.all(eval_all: false)
       if !eval_all && !Homebrew::EnvConfig.eval_all?
         raise ArgumentError, "Cask::Cask#all cannot be used without `--eval-all` or HOMEBREW_EVAL_ALL"
@@ -383,7 +380,6 @@ module Cask
       }
     end
 
-    # @private
     def to_internal_api_hash
       api_hash = {
         "token"              => token,
@@ -426,7 +422,6 @@ module Cask
     HASH_KEYS_TO_SKIP = %w[outdated installed versions].freeze
     private_constant :HASH_KEYS_TO_SKIP
 
-    # @private
     def to_hash_with_variations(hash_method: :to_h)
       case hash_method
       when :to_h

Library/Homebrew/cask/cask_loader.rb

@@ -9,8 +9,6 @@ require "extend/hash/keys"
 
 module Cask
   # Loads a cask from various sources.
-  #
-  # @api private
   module CaskLoader
     extend Context
 

Library/Homebrew/cask/denylist.rb

@@ -3,8 +3,6 @@
 
 module Cask
   # List of casks which are not allowed in official taps.
-  #
-  # @api private
   module Denylist
     sig { params(name: String).returns(T.nilable(String)) }
     def self.reason(name)

Library/Homebrew/cask/download.rb

@@ -8,8 +8,6 @@ require "cask/quarantine"
 
 module Cask
   # A download corresponding to a {Cask}.
-  #
-  # @api private
   class Download < ::Downloadable
     include Context
 

Library/Homebrew/cask/dsl.rb

@@ -30,8 +30,6 @@ require "extend/on_system"
 
 module Cask
   # Class representing the domain-specific language used for casks.
-  #
-  # @api private
   class DSL
     ORDINARY_ARTIFACT_CLASSES = [
       Artifact::Installer,

Library/Homebrew/cask/dsl/base.rb

@@ -7,8 +7,6 @@ require "extend/on_system"
 module Cask
   class DSL
     # Superclass for all stanzas which take a block.
-    #
-    # @api private
     class Base
       extend Forwardable
 

Library/Homebrew/cask/dsl/caveats.rb

@@ -14,8 +14,6 @@ module Cask
     # The return value of the last method in the block is also sent
     # to the output by the caller, but that feature is only for the
     # convenience of cask authors.
-    #
-    # @api private
     class Caveats < Base
       extend Attrable
 

Library/Homebrew/cask/dsl/conflicts_with.rb

@@ -7,8 +7,6 @@ require "extend/hash/keys"
 module Cask
   class DSL
     # Class corresponding to the `conflicts_with` stanza.
-    #
-    # @api private
     class ConflictsWith < SimpleDelegator
       VALID_KEYS = [
         :formula,

Library/Homebrew/cask/dsl/container.rb

@@ -6,8 +6,6 @@ require "unpack_strategy"
 module Cask
   class DSL
     # Class corresponding to the `container` stanza.
-    #
-    # @api private
     class Container
       attr_accessor :nested, :type
 

Library/Homebrew/cask/dsl/depends_on.rb

@@ -8,8 +8,6 @@ require "requirements/macos_requirement"
 module Cask
   class DSL
     # Class corresponding to the `depends_on` stanza.
-    #
-    # @api private
     class DependsOn < SimpleDelegator
       VALID_KEYS = Set.new([
         :formula,

Library/Homebrew/cask/dsl/postflight.rb

@@ -6,8 +6,6 @@ require "cask/staged"
 module Cask
   class DSL
     # Class corresponding to the `postflight` stanza.
-    #
-    # @api private
     class Postflight < Base
       include Staged
 

Library/Homebrew/cask/dsl/preflight.rb

@@ -6,8 +6,6 @@ require "cask/staged"
 module Cask
   class DSL
     # Class corresponding to the `preflight` stanza.
-    #
-    # @api private
     class Preflight < Base
       include Staged
     end

Library/Homebrew/cask/dsl/uninstall_postflight.rb

@@ -4,8 +4,6 @@
 module Cask
   class DSL
     # Class corresponding to the `uninstall_postflight` stanza.
-    #
-    # @api private
     class UninstallPostflight < Base
     end
   end

Library/Homebrew/cask/dsl/uninstall_preflight.rb

@@ -6,8 +6,6 @@ require "cask/staged"
 module Cask
   class DSL
     # Class corresponding to the `uninstall_preflight` stanza.
-    #
-    # @api private
     class UninstallPreflight < Base
       include Staged
     end

Library/Homebrew/cask/dsl/version.rb

@@ -4,8 +4,6 @@
 module Cask
   class DSL
     # Class corresponding to the `version` stanza.
-    #
-    # @api private
     class Version < ::String
       DIVIDERS = {
         "." => :dots,

Library/Homebrew/cask/exceptions.rb

@@ -3,13 +3,9 @@
 
 module Cask
   # General cask error.
-  #
-  # @api private
   class CaskError < RuntimeError; end
 
   # Cask error containing multiple other errors.
-  #
-  # @api private
   class MultipleCaskErrors < CaskError
     def initialize(errors)
       super()
@@ -28,8 +24,6 @@ module Cask
   end
 
   # Abstract cask error containing a cask token.
-  #
-  # @api private
   class AbstractCaskErrorWithToken < CaskError
     sig { returns(String) }
     attr_reader :token
@@ -46,8 +40,6 @@ module Cask
   end
 
   # Error when a cask is not installed.
-  #
-  # @api private
   class CaskNotInstalledError < AbstractCaskErrorWithToken
     # @!visibility private
     sig { returns(String) }
@@ -57,8 +49,6 @@ module Cask
   end
 
   # Error when a cask cannot be installed.
-  #
-  # @api private
   class CaskCannotBeInstalledError < AbstractCaskErrorWithToken
     attr_reader :message
 
@@ -75,8 +65,6 @@ module Cask
   end
 
   # Error when a cask conflicts with another cask.
-  #
-  # @api private
   class CaskConflictError < AbstractCaskErrorWithToken
     attr_reader :conflicting_cask
 
@@ -93,8 +81,6 @@ module Cask
   end
 
   # Error when a cask is not available.
-  #
-  # @api private
   class CaskUnavailableError < AbstractCaskErrorWithToken
     # @!visibility private
     sig { returns(String) }
@@ -104,8 +90,6 @@ module Cask
   end
 
   # Error when a cask is unreadable.
-  #
-  # @api private
   class CaskUnreadableError < CaskUnavailableError
     # @!visibility private
     sig { returns(String) }
@@ -115,8 +99,6 @@ module Cask
   end
 
   # Error when a cask in a specific tap is not available.
-  #
-  # @api private
   class TapCaskUnavailableError < CaskUnavailableError
     attr_reader :tap
 
@@ -135,8 +117,6 @@ module Cask
   end
 
   # Error when a cask with the same name is found in multiple taps.
-  #
-  # @api private
   class TapCaskAmbiguityError < CaskError
     sig { returns(String) }
     attr_reader :token
@@ -161,8 +141,6 @@ module Cask
   end
 
   # Error when a cask already exists.
-  #
-  # @api private
   class CaskAlreadyCreatedError < AbstractCaskErrorWithToken
     # @!visibility private
     sig { returns(String) }
@@ -172,8 +150,6 @@ module Cask
   end
 
   # Error when there is a cyclic cask dependency.
-  #
-  # @api private
   class CaskCyclicDependencyError < AbstractCaskErrorWithToken
     # @!visibility private
     sig { returns(String) }
@@ -183,8 +159,6 @@ module Cask
   end
 
   # Error when a cask depends on itself.
-  #
-  # @api private
   class CaskSelfReferencingDependencyError < CaskCyclicDependencyError
     # @!visibility private
     sig { returns(String) }
@@ -194,8 +168,6 @@ module Cask
   end
 
   # Error when no cask is specified.
-  #
-  # @api private
   class CaskUnspecifiedError < CaskError
     # @!visibility private
     sig { returns(String) }
@@ -205,8 +177,6 @@ module Cask
   end
 
   # Error when a cask is invalid.
-  #
-  # @api private
   class CaskInvalidError < AbstractCaskErrorWithToken
     # @!visibility private
     sig { returns(String) }
@@ -216,8 +186,6 @@ module Cask
   end
 
   # Error when a cask token does not match the file name.
-  #
-  # @api private
   class CaskTokenMismatchError < CaskInvalidError
     def initialize(token, header_token)
       super(token, "Token '#{header_token}' in header line does not match the file name.")
@@ -225,8 +193,6 @@ module Cask
   end
 
   # Error during quarantining of a file.
-  #
-  # @api private
   class CaskQuarantineError < CaskError
     attr_reader :path, :reason
 
@@ -253,8 +219,6 @@ module Cask
   end
 
   # Error while propagating quarantine information to subdirectories.
-  #
-  # @api private
   class CaskQuarantinePropagationError < CaskQuarantineError
     # @!visibility private
     sig { returns(String) }
@@ -272,8 +236,6 @@ module Cask
   end
 
   # Error while removing quarantine information.
-  #
-  # @api private
   class CaskQuarantineReleaseError < CaskQuarantineError
     # @!visibility private
     sig { returns(String) }

Library/Homebrew/cask/info.rb

@@ -4,8 +4,6 @@
 require "json"
 
 module Cask
-  #
-  # @api private
   class Info
     def self.get_info(cask)
       require "cask/installer"

Library/Homebrew/cask/installer.rb

@@ -15,8 +15,6 @@ require "cgi"
 
 module Cask
   # Installer for a {Cask}.
-  #
-  # @api private
   class Installer
     extend Attrable
 

Library/Homebrew/cask/list.rb

@@ -4,7 +4,6 @@
 require "cask/artifact/relocated"
 
 module Cask
-  # @api private
   class List
     def self.list_casks(*casks, one: false, full_name: false, versions: false)
       output = if casks.any?

Library/Homebrew/cask/metadata.rb

@@ -3,8 +3,6 @@
 
 module Cask
   # Helper module for reading and writing cask metadata.
-  #
-  # @api private
   module Metadata
     METADATA_SUBDIR = ".metadata"
     TIMESTAMP_FORMAT = "%Y%m%d%H%M%S.%L"

Library/Homebrew/cask/pkg.rb

@@ -5,8 +5,6 @@ require "cask/macos"
 
 module Cask
   # Helper class for uninstalling `.pkg` installers.
-  #
-  # @api private
   class Pkg
     sig { params(regexp: String, command: T.class_of(SystemCommand)).returns(T::Array[Pkg]) }
     def self.all_matching(regexp, command)

Library/Homebrew/cask/quarantine.rb

@@ -7,8 +7,6 @@ require "system_command"
 
 module Cask
   # Helper module for quarantining files.
-  #
-  # @api private
   module Quarantine
     extend SystemCommand::Mixin
 

Library/Homebrew/cask/reinstall.rb

@@ -2,8 +2,6 @@
 # frozen_string_literal: true
 
 module Cask
-  #
-  # @api private
   class Reinstall
     def self.reinstall_casks(
       *casks,

Library/Homebrew/cask/staged.rb

@@ -5,8 +5,6 @@ require "utils/user"
 
 module Cask
   # Helper functions for staged casks.
-  #
-  # @api private
   module Staged
     # FIXME: Enable cop again when https://github.com/sorbet/sorbet/issues/3532 is fixed.
     # rubocop:disable Style/MutableConstant

Library/Homebrew/cask/uninstall.rb

@@ -2,7 +2,6 @@
 # frozen_string_literal: true
 
 module Cask
-  # @api private
   class Uninstall
     def self.uninstall_casks(*casks, binaries: nil, force: false, verbose: false)
       require "cask/installer"

Library/Homebrew/cask/upgrade.rb

@@ -5,7 +5,6 @@ require "env_config"
 require "cask/config"
 
 module Cask
-  # @api private
   class Upgrade
     sig {
       params(

Library/Homebrew/cask/url.rb

@@ -6,10 +6,7 @@ require "utils/curl"
 
 module Cask
   # Class corresponding to the `url` stanza.
-  #
-  # @api private
   class URL < Delegator
-    # @api private
     class DSL
       attr_reader :uri, :specs,
                   :verified, :using,
@@ -79,7 +76,6 @@ module Cask
       end
     end
 
-    # @api private
     class BlockDSL
       # To access URL associated with page contents.
       module PageWithURL

Library/Homebrew/cask/utils.rb

@@ -8,8 +8,6 @@ BUG_REPORTS_URL = "https://github.com/Homebrew/homebrew-cask#reporting-bugs"
 
 module Cask
   # Helper functions for various cask operations.
-  #
-  # @api private
   module Utils
     def self.gain_permissions_mkpath(path, command: SystemCommand)
       dir = path.ascend.find(&:directory?)

Library/Homebrew/caveats.rb

@@ -5,8 +5,6 @@ require "language/python"
 require "utils/service"
 
 # A formula's caveats.
-#
-# @api private
 class Caveats
   extend Forwardable
 

Library/Homebrew/checksum.rb

@@ -2,8 +2,6 @@
 # frozen_string_literal: true
 
 # A formula's checksum.
-#
-# @api private
 class Checksum
   extend Forwardable
 

Library/Homebrew/cleanup.rb

@@ -10,8 +10,6 @@ require "set"
 
 module Homebrew
   # Helper class for cleaning up the Homebrew cache.
-  #
-  # @api private
   class Cleanup
     CLEANUP_DEFAULT_DAYS = Homebrew::EnvConfig.cleanup_periodic_full_days.to_i.freeze
     private_constant :CLEANUP_DEFAULT_DAYS

Library/Homebrew/cli/named_args.rb

@@ -8,8 +8,6 @@ require "cli/args"
 module Homebrew
   module CLI
     # Helper class for loading formulae/casks from named arguments.
-    #
-    # @api private
     class NamedArgs < Array
       sig {
         params(

Library/Homebrew/commands.rb

@@ -4,8 +4,6 @@
 require "completions"
 
 # Helper functions for commands.
-#
-# @api private
 module Commands
   HOMEBREW_CMD_PATH = (HOMEBREW_LIBRARY_PATH/"cmd").freeze
   HOMEBREW_DEV_CMD_PATH = (HOMEBREW_LIBRARY_PATH/"dev-cmd").freeze

Library/Homebrew/compilers.rb

@@ -1,7 +1,6 @@
 # typed: true
 # frozen_string_literal: true
 
-# @private
 module CompilerConstants
   GNU_GCC_VERSIONS = %w[4.9 5 6 7 8 9 10 11 12 13].freeze
   GNU_GCC_REGEXP = /^gcc-(4\.9|[5-9]|10|11|12|13)$/
@@ -16,8 +15,6 @@ module CompilerConstants
 end
 
 # Class for checking compiler compatibility for a formula.
-#
-# @api private
 class CompilerFailure
   attr_reader :type
 
@@ -99,8 +96,6 @@ class CompilerFailure
 end
 
 # Class for selecting a compiler for a formula.
-#
-# @api private
 class CompilerSelector
   include CompilerConstants
 

Library/Homebrew/completions.rb

@@ -7,8 +7,6 @@ require "erb"
 
 module Homebrew
   # Helper functions for generating shell completions.
-  #
-  # @api private
   module Completions
     Variables = Struct.new(
       :aliases,

Library/Homebrew/context.rb

@@ -4,8 +4,6 @@
 require "monitor"
 
 # Module for querying the current execution context.
-#
-# @api private
 module Context
   extend MonitorMixin
 

Library/Homebrew/debrew.rb

@@ -6,8 +6,6 @@ require "mutex_m"
 require "ignorable"
 
 # Helper module for debugging formulae.
-#
-# @api private
 module Debrew
   extend Mutex_m
 

Library/Homebrew/debrew/irb.rb

@@ -3,7 +3,6 @@
 
 require "irb"
 
-# @private
 module IRB
   def self.start_within(binding)
     unless @setup_done

Library/Homebrew/dependable.rb

@@ -4,8 +4,6 @@
 require "options"
 
 # Shared functions for classes which can be depended upon.
-#
-# @api private
 module Dependable
   # `:run` and `:linked` are no longer used but keep them here to avoid their
   # misuse in future.

Library/Homebrew/dependencies.rb

@@ -4,8 +4,6 @@
 require "delegate"
 
 # A collection of dependencies.
-#
-# @api private
 class Dependencies < SimpleDelegator
   def initialize(*args)
     super(args)
@@ -45,8 +43,6 @@ class Dependencies < SimpleDelegator
 end
 
 # A collection of requirements.
-#
-# @api private
 class Requirements < SimpleDelegator
   def initialize(*args)
     super(Set.new(args))

Library/Homebrew/dependencies_helpers.rb

@@ -4,8 +4,6 @@
 require "cask_dependent"
 
 # Helper functions for dependencies.
-#
-# @api private
 module DependenciesHelpers
   def args_includes_ignores(args)
     includes = [:required?, :recommended?] # included by default

Library/Homebrew/dependency.rb

@@ -4,8 +4,6 @@
 require "dependable"
 
 # A dependency on another Homebrew formula.
-#
-# @api private
 class Dependency
   extend Forwardable
   include Dependable
@@ -28,10 +26,6 @@ class Dependency
     @tap, = tap_with_name
   end
 
-  # @!visibility private
-  sig { returns(String) }
-  def to_s = name
-
   def ==(other)
     instance_of?(other.class) && name == other.name && tags == other.tags
   end
@@ -100,6 +94,10 @@ class Dependency
     false
   end
 
+  # @!visibility private
+  sig { returns(String) }
+  def to_s = name
+
   # @!visibility private
   sig { returns(String) }
   def inspect

Library/Homebrew/dependency_collector.rb

@@ -158,7 +158,7 @@ class DependencyCollector
 
   def parse_symbol_spec(spec, tags)
     # When modifying this list of supported requirements, consider
-    # whether Formulary::API_SUPPORTED_REQUIREMENTS should also be changed.
+    # whether `Formulary::API_SUPPORTED_REQUIREMENTS` should also be changed.
     case spec
     when :arch          then ArchRequirement.new(tags)
     when :codesign      then CodesignRequirement.new(tags)

Library/Homebrew/deprecate_disable.rb

@@ -2,8 +2,6 @@
 # frozen_string_literal: true
 
 # Helper module for handling `disable!` and `deprecate!`.
-#
-# @api private
 module DeprecateDisable
   module_function
 

Library/Homebrew/descriptions.rb

@@ -6,8 +6,6 @@ require "formula_versions"
 require "search"
 
 # Helper class for printing and searching descriptions.
-#
-# @api private
 class Descriptions
   # Given a regex, find all formulae whose specified fields contain a match.
   def self.search(string_or_regex, field, cache_store, eval_all = Homebrew::EnvConfig.eval_all?)

Library/Homebrew/dev-cmd/rubydoc.rb

@@ -0,0 +1,37 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+
+module Homebrew
+  module DevCmd
+    class Rubydoc < AbstractCommand
+      cmd_args do
+        description <<~EOS
+          Generate Homebrew's RubyDoc documentation.
+        EOS
+        switch "--only-public",
+               description: "Only generate public API documentation."
+        switch "--open",
+               description: "Open generated documentation in a browser."
+      end
+
+      sig { override.void }
+      def run
+        Homebrew.install_bundler_gems!(groups: ["doc"])
+
+        HOMEBREW_LIBRARY_PATH.cd do
+          no_api_args = if args.only_public?
+            ["--hide-api", "private", "--hide-api", "internal"]
+          else
+            []
+          end
+
+          system "bundle", "exec", "yard", "doc", "--output", "doc", *no_api_args
+
+          exec_browser "file://#{HOMEBREW_LIBRARY_PATH}/doc/index.html" if args.open?
+        end
+      end
+    end
+  end
+end

Library/Homebrew/development_tools.rb

@@ -3,9 +3,14 @@
 
 require "version"
 
-# @private
+# Helper class for gathering information about development tools.
+#
+# @api public
 class DevelopmentTools
   class << self
+    # Locate a development tool.
+    #
+    # @api public
     sig { params(tool: T.any(String, Symbol)).returns(T.nilable(Pathname)) }
     def locate(tool)
       # Don't call tools (cc, make, strip, etc.) directly!
@@ -44,11 +49,17 @@ class DevelopmentTools
         "Checksums will still be verified."
     end
 
+    # Get the default C compiler.
+    #
+    # @api public
     sig { returns(Symbol) }
     def default_compiler
       :clang
     end
 
+    # Get the Clang version.
+    #
+    # @api public
     sig { returns(Version) }
     def clang_version
       @clang_version ||= if (path = locate("clang")) &&
@@ -59,6 +70,9 @@ class DevelopmentTools
       end
     end
 
+    # Get the Clang build version.
+    #
+    # @api public
     sig { returns(Version) }
     def clang_build_version
       @clang_build_version ||= if (path = locate("clang")) &&
@@ -70,6 +84,9 @@ class DevelopmentTools
       end
     end
 
+    # Get the LLVM Clang build version.
+    #
+    # @api public
     sig { returns(Version) }
     def llvm_clang_build_version
       @llvm_clang_build_version ||= begin

Library/Homebrew/diagnostic.rb

@@ -15,8 +15,6 @@ require "system_command"
 
 module Homebrew
   # Module containing diagnostic checks.
-  #
-  # @api private
   module Diagnostic
     def self.missing_deps(formulae, hide = nil)
       missing = {}