From b89d282d5cfc475760ab3407ebe4e8c12edc55d0 Mon Sep 17 00:00:00 2001
From: Michael Cho <michael@michaelcho.dev>
Date: Wed, 16 Oct 2024 11:54:21 -0400
Subject: [PATCH] formula: change some private API to public API

The following methods used in Homebrew/core are now public API:

* `system`
* `std_*_args`
* `any_version_installed?`
* `shared_library`
* `rpath`
* `loader_path`
* `deuniversalize_machos`
* `generate_completions_from_executable`

Also remove duplicate typing in `generate_completions_from_executable`
---
 Library/Homebrew/formula.rb | 38 +++++++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb
index 1bea34ff0f161..900960552656b 100644
--- a/Library/Homebrew/formula.rb
+++ b/Library/Homebrew/formula.rb
@@ -645,6 +645,8 @@ def latest_version_installed?
   end
 
   # If at least one version of {Formula} is installed.
+  #
+  # @api public
   sig { returns(T::Boolean) }
   def any_version_installed?
     installed_prefixes.any? { |keg| (keg/AbstractTab::FILENAME).file? }
@@ -1779,6 +1781,8 @@ def inspect
   end
 
   # Standard parameters for cabal-v2 builds.
+  #
+  # @api public
   sig { returns(T::Array[String]) }
   def std_cabal_v2_args
     # cabal-install's dependency-resolution backtracking strategy can
@@ -1791,6 +1795,8 @@ def std_cabal_v2_args
   end
 
   # Standard parameters for cargo builds.
+  #
+  # @api public
   sig {
     params(root: T.any(String, Pathname), path: T.any(String, Pathname)).returns(T::Array[String])
   }
@@ -1803,6 +1809,8 @@ def std_cargo_args(root: prefix, path: ".")
   # Setting `CMAKE_FIND_FRAMEWORK` to "LAST" tells CMake to search for our
   # libraries before trying to utilize Frameworks, many of which will be from
   # 3rd party installs.
+  #
+  # @api public
   sig {
     params(
       install_prefix: T.any(String, Pathname),
@@ -1824,6 +1832,8 @@ def std_cmake_args(install_prefix: prefix, install_libdir: "lib", find_framework
   end
 
   # Standard parameters for configure builds.
+  #
+  # @api public
   sig {
     params(
       prefix: T.any(String, Pathname),
@@ -1836,6 +1846,8 @@ def std_configure_args(prefix: self.prefix, libdir: "lib")
   end
 
   # Standard parameters for Go builds.
+  #
+  # @api public
   sig {
     params(output:  T.any(String, Pathname),
            ldflags: T.nilable(T.any(String, T::Array[String]))).returns(T::Array[String])
@@ -1847,12 +1859,16 @@ def std_go_args(output: bin/name, ldflags: nil)
   end
 
   # Standard parameters for meson builds.
+  #
+  # @api public
   sig { returns(T::Array[String]) }
   def std_meson_args
     ["--prefix=#{prefix}", "--libdir=#{lib}", "--buildtype=release", "--wrap-mode=nofallback"]
   end
 
   # Standard parameters for npm builds.
+  #
+  # @api public
   sig { params(prefix: T.any(String, Pathname, FalseClass)).returns(T::Array[String]) }
   def std_npm_args(prefix: libexec)
     require "language/node"
@@ -1863,6 +1879,8 @@ def std_npm_args(prefix: libexec)
   end
 
   # Standard parameters for pip builds.
+  #
+  # @api public
   sig {
     params(prefix:          T.any(String, Pathname, FalseClass),
            build_isolation: T::Boolean).returns(T::Array[String])
@@ -1889,6 +1907,8 @@ def std_pip_args(prefix: self.prefix, build_isolation: false)
   # shared_library("foo", "*") #=> foo.2.dylib, foo.1.dylib, foo.dylib
   # shared_library("*")        #=> foo.dylib, bar.dylib
   # ```
+  #
+  # @api public
   sig { params(name: String, version: T.nilable(T.any(String, Integer))).returns(String) }
   def shared_library(name, version = nil)
     return "*.dylib" if name == "*" && (version.blank? || version == "*")
@@ -1913,6 +1933,8 @@ def shared_library(name, version = nil)
   # rpath(target: frameworks) #=> "@loader_path/../Frameworks"
   # rpath(source: libexec/"bin") #=> "@loader_path/../../lib"
   # ```
+  #
+  # @api public
   sig { params(source: Pathname, target: Pathname).returns(String) }
   def rpath(source: bin, target: lib)
     unless target.to_s.start_with?(HOMEBREW_PREFIX)
@@ -1922,6 +1944,9 @@ def rpath(source: bin, target: lib)
     "#{loader_path}/#{target.relative_path_from(source)}"
   end
 
+  # Linker variable for the directory containing the program or shared object.
+  #
+  # @api public
   sig { returns(String) }
   def loader_path
     "@loader_path"
@@ -1943,6 +1968,8 @@ def time
   #
   # If called with no parameters, does this with all compatible
   # universal binaries in a {Formula}'s {Keg}.
+  #
+  # @api public
   sig { params(targets: T.nilable(T.any(Pathname, String))).void }
   def deuniversalize_machos(*targets)
     if targets.none?
@@ -2049,13 +2076,14 @@ def extract_macho_slice_from(file, arch = Hardware::CPU.arch)
   #                                                     "completions", "--selected-shell=bash")
   # ```
   #
-  # @param commands [Pathname, String]
+  # @api public
+  # @param commands
   #   the path to the executable and any passed subcommand(s) to use for generating the completion scripts.
-  # @param base_name [String]
+  # @param base_name
   #   the base name of the generated completion script. Defaults to the formula name.
-  # @param shells [Array<Symbol>]
+  # @param shells
   #   the shells to generate completion scripts for. Defaults to `[:bash, :zsh, :fish]`.
-  # @param shell_parameter_format [String, Symbol]
+  # @param shell_parameter_format
   #   specify how `shells` should each be passed to the `executable`. Takes either a String representing a
   #   prefix, or one of `[:flag, :arg, :none, :click]`. Defaults to plainly passing the shell.
   sig {
@@ -2974,6 +3002,8 @@ def undeclared_runtime_dependencies
   # ```ruby
   # system "make", "install"
   # ```
+  #
+  # @api public
   sig { params(cmd: T.any(String, Pathname), args: T.any(String, Integer, Pathname, Symbol)).void }
   def system(cmd, *args)
     verbose_using_dots = Homebrew::EnvConfig.verbose_using_dots?