Make documentation @api private by default.

Homebrew · Apr 26, 2024 · 01f2fdd · 01f2fdd
1 parent caff135
commit 01f2fdd
Show file tree

Hide file tree

Showing 239 changed files with 225 additions and 866 deletions.
diff --git a/Library/Homebrew/.yardopts b/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/

diff --git a/Library/Homebrew/Gemfile b/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

diff --git a/Library/Homebrew/Gemfile.lock b/Library/Homebrew/Gemfile.lock
@@ -198,6 +198,8 @@ DEPENDENCIES
   stackprof
   tapioca
   warning
+  yard
+  yard-sorbet
 
 RUBY VERSION
    ruby 3.1.4p223

diff --git a/Library/Homebrew/PATH.rb b/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

diff --git a/Library/Homebrew/api.rb b/Library/Homebrew/api.rb
@@ -9,8 +9,6 @@
 
 module Homebrew
   # Helper functions for using Homebrew's formulae.brew.sh API.
-  #
-  # @api private
   module API
     extend Cachable
 
@@ -191,15 +189,13 @@ def self.internal_json_v3?
     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?
 
     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

diff --git a/Library/Homebrew/api/analytics.rb b/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) }

diff --git a/Library/Homebrew/api/cask.rb b/Library/Homebrew/api/cask.rb
@@ -7,8 +7,6 @@
 module Homebrew
   module API
     # Helper functions for using the cask JSON API.
-    #
-    # @api private
     module Cask
       extend Cachable
 

diff --git a/Library/Homebrew/api/download.rb b/Library/Homebrew/api/download.rb
@@ -5,15 +5,13 @@
 
 module Homebrew
   module API
-    # @api private
     class DownloadStrategy < CurlDownloadStrategy
       sig { override.returns(Pathname) }
       def symlink_location
         cache/name
       end
     end
 
-    # @api private
     class Download < Downloadable
       sig {
         params(

diff --git a/Library/Homebrew/api/formula.rb b/Library/Homebrew/api/formula.rb
@@ -7,8 +7,6 @@
 module Homebrew
   module API
     # Helper functions for using the formula JSON API.
-    #
-    # @api private
     module Formula
       extend Cachable
 

diff --git a/Library/Homebrew/build.rb b/Library/Homebrew/build.rb
@@ -17,8 +17,6 @@
 require "cmd/install"
 
 # A formula build.
-#
-# @api private
 class Build
   attr_reader :formula, :deps, :reqs, :args
 

diff --git a/Library/Homebrew/build_environment.rb b/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)

diff --git a/Library/Homebrew/build_options.rb b/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 @@ def any_args_or_options?
     !@args.empty? || !@options.empty?
   end
 
-  # @private
   def used_options
     @options & @args
   end
 
-  # @private
   def unused_options
     @options - @args
   end

diff --git a/Library/Homebrew/bump_version_parser.rb b/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

diff --git a/Library/Homebrew/bundle_version.rb b/Library/Homebrew/bundle_version.rb
@@ -5,8 +5,6 @@
 
 module Homebrew
   # Representation of a macOS bundle version, commonly found in `Info.plist` files.
-  #
-  # @api private
   class BundleVersion
     include Comparable
 

diff --git a/Library/Homebrew/cask/artifact.rb b/Library/Homebrew/cask/artifact.rb
@@ -30,8 +30,6 @@
 
 module Cask
   # Module containing all cask artifact classes.
-  #
-  # @api private
   module Artifact
   end
 end
diff --git a/Library/Homebrew/cask/artifact/abstract_artifact.rb b/Library/Homebrew/cask/artifact/abstract_artifact.rb
@@ -7,8 +7,6 @@
 module Cask
   module Artifact
     # Abstract superclass for all artifacts.
-    #
-    # @api private
     class AbstractArtifact
       extend T::Helpers
       abstract!

diff --git a/Library/Homebrew/cask/artifact/abstract_flight_block.rb b/Library/Homebrew/cask/artifact/abstract_flight_block.rb
@@ -6,8 +6,6 @@
 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

diff --git a/Library/Homebrew/cask/artifact/abstract_uninstall.rb b/Library/Homebrew/cask/artifact/abstract_uninstall.rb
@@ -12,8 +12,6 @@
 module Cask
   module Artifact
     # Abstract superclass for uninstall artifacts.
-    #
-    # @api private
     class AbstractUninstall < AbstractArtifact
       include SystemCommand::Mixin
 

diff --git a/Library/Homebrew/cask/artifact/app.rb b/Library/Homebrew/cask/artifact/app.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `app` stanza.
-    #
-    # @api private
     class App < Moved
     end
   end

diff --git a/Library/Homebrew/cask/artifact/artifact.rb b/Library/Homebrew/cask/artifact/artifact.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Generic artifact corresponding to the `artifact` stanza.
-    #
-    # @api private
     class Artifact < Moved
       sig { returns(String) }
       def self.english_name

diff --git a/Library/Homebrew/cask/artifact/audio_unit_plugin.rb b/Library/Homebrew/cask/artifact/audio_unit_plugin.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `audio_unit_plugin` stanza.
-    #
-    # @api private
     class AudioUnitPlugin < Moved
     end
   end

diff --git a/Library/Homebrew/cask/artifact/binary.rb b/Library/Homebrew/cask/artifact/binary.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `binary` stanza.
-    #
-    # @api private
     class Binary < Symlinked
       def link(command: nil, **options)
         super(command:, **options)

diff --git a/Library/Homebrew/cask/artifact/colorpicker.rb b/Library/Homebrew/cask/artifact/colorpicker.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `colorpicker` stanza.
-    #
-    # @api private
     class Colorpicker < Moved
     end
   end

diff --git a/Library/Homebrew/cask/artifact/dictionary.rb b/Library/Homebrew/cask/artifact/dictionary.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `dictionary` stanza.
-    #
-    # @api private
     class Dictionary < Moved
     end
   end

diff --git a/Library/Homebrew/cask/artifact/font.rb b/Library/Homebrew/cask/artifact/font.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `font` stanza.
-    #
-    # @api private
     class Font < Moved
     end
   end

diff --git a/Library/Homebrew/cask/artifact/input_method.rb b/Library/Homebrew/cask/artifact/input_method.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `input_method` stanza.
-    #
-    # @api private
     class InputMethod < Moved
     end
   end

diff --git a/Library/Homebrew/cask/artifact/installer.rb b/Library/Homebrew/cask/artifact/installer.rb
@@ -7,8 +7,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `installer` stanza.
-    #
-    # @api private
     class Installer < AbstractArtifact
       VALID_KEYS = Set.new([
         :manual,

diff --git a/Library/Homebrew/cask/artifact/internet_plugin.rb b/Library/Homebrew/cask/artifact/internet_plugin.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `internet_plugin` stanza.
-    #
-    # @api private
     class InternetPlugin < Moved
     end
   end

diff --git a/Library/Homebrew/cask/artifact/keyboard_layout.rb b/Library/Homebrew/cask/artifact/keyboard_layout.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `keyboard_layout` stanza.
-    #
-    # @api private
     class KeyboardLayout < Moved
       def install_phase(**options)
         super(**options)

diff --git a/Library/Homebrew/cask/artifact/manpage.rb b/Library/Homebrew/cask/artifact/manpage.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `manpage` stanza.
-    #
-    # @api private
     class Manpage < Symlinked
       attr_reader :section
 

diff --git a/Library/Homebrew/cask/artifact/mdimporter.rb b/Library/Homebrew/cask/artifact/mdimporter.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `mdimporter` stanza.
-    #
-    # @api private
     class Mdimporter < Moved
       sig { returns(String) }
       def self.english_name

diff --git a/Library/Homebrew/cask/artifact/moved.rb b/Library/Homebrew/cask/artifact/moved.rb
@@ -7,8 +7,6 @@
 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

diff --git a/Library/Homebrew/cask/artifact/pkg.rb b/Library/Homebrew/cask/artifact/pkg.rb
@@ -10,8 +10,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `pkg` stanza.
-    #
-    # @api private
     class Pkg < AbstractArtifact
       attr_reader :path, :stanza_options
 

diff --git a/Library/Homebrew/cask/artifact/postflight_block.rb b/Library/Homebrew/cask/artifact/postflight_block.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `postflight` stanza.
-    #
-    # @api private
     class PostflightBlock < AbstractFlightBlock
     end
   end

diff --git a/Library/Homebrew/cask/artifact/preflight_block.rb b/Library/Homebrew/cask/artifact/preflight_block.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `preflight` stanza.
-    #
-    # @api private
     class PreflightBlock < AbstractFlightBlock
     end
   end

diff --git a/Library/Homebrew/cask/artifact/prefpane.rb b/Library/Homebrew/cask/artifact/prefpane.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `prefpane` stanza.
-    #
-    # @api private
     class Prefpane < Moved
       sig { returns(String) }
       def self.english_name

diff --git a/Library/Homebrew/cask/artifact/qlplugin.rb b/Library/Homebrew/cask/artifact/qlplugin.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `qlplugin` stanza.
-    #
-    # @api private
     class Qlplugin < Moved
       sig { returns(String) }
       def self.english_name

diff --git a/Library/Homebrew/cask/artifact/relocated.rb b/Library/Homebrew/cask/artifact/relocated.rb
@@ -7,8 +7,6 @@
 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

diff --git a/Library/Homebrew/cask/artifact/screen_saver.rb b/Library/Homebrew/cask/artifact/screen_saver.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `screen_saver` stanza.
-    #
-    # @api private
     class ScreenSaver < Moved
     end
   end

diff --git a/Library/Homebrew/cask/artifact/service.rb b/Library/Homebrew/cask/artifact/service.rb
@@ -6,8 +6,6 @@
 module Cask
   module Artifact
     # Artifact corresponding to the `service` stanza.
-    #
-    # @api private
     class Service < Moved
     end
   end