Improve documentation and add type signatures.

Library/Homebrew/formula.rb

@@ -67,15 +67,6 @@ class Formula
   extend Predicable
 
   # @!method inreplace(paths, before = nil, after = nil)
-  # Actually implemented in {Utils::Inreplace.inreplace}.
-  # Sometimes we have to change a bit before we install. Mostly we
-  # prefer a patch but if you need the `prefix` of this formula in the
-  # patch you have to resort to `inreplace`, because in the patch
-  # you don't have access to any variable defined by the formula. Only
-  # `HOMEBREW_PREFIX` is available in the embedded patch.
-  #
-  # `inreplace` supports regular expressions:
-  # <pre>inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"</pre>
   # @see Utils::Inreplace.inreplace
 
   # The name of this {Formula}.
@@ -590,6 +581,7 @@ class Formula
   end
 
   # {PkgVersion} of the linked keg for the formula.
+  sig { returns(T.nilable(PkgVersion)) }
   def linked_version
     return unless linked?
 
@@ -668,9 +660,12 @@ class Formula
 
   # The directory where the formula's binaries should be installed.
   # This is not symlinked into `HOMEBREW_PREFIX`.
-  # It is also commonly used to install files that we do not wish to be
+  # It is commonly used to install files that we do not wish to be
   # symlinked into `HOMEBREW_PREFIX` from one of the other directories and
   # instead manually create symlinks or wrapper scripts into e.g. {#bin}.
+  # <pre>libexec.install "foo.jar"
+  # bin.write_jar_script libexec/"foo.jar", "foo"
+  # </pre>
   def libexec
     prefix/"libexec"
   end
@@ -1104,14 +1099,9 @@ class Formula
   # @private
   delegate keg_only_reason: :"self.class"
 
-  # sometimes the formula cleaner breaks things
+  # @see .skip_clean
-  # skip cleaning paths in a formula with a class method like this:
-  #   skip_clean "bin/foo", "lib/bar"
-  # keep .la files with:
-  #   skip_clean :la
   # @private
   sig { params(path: Pathname).returns(T::Boolean) }
-
   def skip_clean?(path)
     return true if path.extname == ".la" && self.class.skip_clean_paths.include?(:la)
 
@@ -1119,11 +1109,7 @@ class Formula
     self.class.skip_clean_paths.include? to_check
   end
 
-  # Sometimes we accidentally install files outside prefix. After we fix that,
+  # @see .link_overwrite
-  # users will get nasty link conflict error. So we create an allowlist here to
-  # allow overwriting certain files. e.g.
-  #   link_overwrite "bin/foo", "lib/bar"
-  #   link_overwrite "share/man/man1/baz-*"
   # @private
   def link_overwrite?(path)
     # Don't overwrite files not created by Homebrew.
@@ -1163,36 +1149,42 @@ class Formula
   # Defaults to false.
   # @!method deprecated?
   # @return [Boolean]
+  # @see .deprecate!
   delegate deprecated?: :"self.class"
 
   # The date that this {Formula} was or becomes deprecated.
   # Returns `nil` if no date is specified.
   # @!method deprecation_date
   # @return Date
+  # @see .deprecate!
   delegate deprecation_date: :"self.class"
 
   # The reason this {Formula} is deprecated.
   # Returns `nil` if no reason is specified or the formula is not deprecated.
   # @!method deprecation_reason
   # @return [String, Symbol]
+  # @see .deprecate!
   delegate deprecation_reason: :"self.class"
 
   # Whether this {Formula} is disabled (i.e. cannot be installed).
   # Defaults to false.
   # @!method disabled?
   # @return [Boolean]
+  # @see .disable!
   delegate disabled?: :"self.class"
 
   # The date that this {Formula} was or becomes disabled.
   # Returns `nil` if no date is specified.
   # @!method disable_date
   # @return Date
+  # @see .disable!
   delegate disable_date: :"self.class"
 
   # The reason this {Formula} is disabled.
   # Returns `nil` if no reason is specified or the formula is not disabled.
   # @!method disable_reason
   # @return [String, Symbol]
+  # @see .disable!
   delegate disable_reason: :"self.class"
 
   sig { returns(T::Boolean) }
@@ -1406,21 +1398,22 @@ class Formula
   end
 
   # Standard parameters for configure builds.
+  sig { returns(T::Array[String]) }
   def std_configure_args
     ["--disable-debug", "--disable-dependency-tracking", "--prefix=#{prefix}", "--libdir=#{lib}"]
   end
 
   # Standard parameters for cargo builds.
+  sig { returns(T::Array[T.any(String, Pathname)]) }
   def std_cargo_args
     ["--locked", "--root", prefix, "--path", "."]
   end
 
   # Standard parameters for CMake builds.
+  #
   # 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.
-  # Note that there isn't a std_autotools variant because autotools is a lot
-  # less consistent and the standard parameters are more memorable.
   sig { returns(T::Array[String]) }
   def std_cmake_args
     args = %W[
@@ -1445,6 +1438,7 @@ class Formula
   end
 
   # Standard parameters for Go builds.
+  sig { returns(T::Array[T.any(String, Pathname)]) }
   def std_go_args
     ["-trimpath", "-o", bin/name]
   end
@@ -1469,6 +1463,20 @@ class Formula
     ["--prefix=#{prefix}", "--libdir=#{lib}", "--buildtype=release", "--wrap-mode=nofallback"]
   end
 
+  # Shared library names according to platform conventions.
+  #
+  # Optionally specify a `version` to restrict the shared library to a specific
+  # version. The special string "*" matches any version.
+  #
+  # If `name` is specified as "*", match any shared library of any version.
+  #
+  # <pre>
+  # shared_library("foo")      #=> foo.dylib
+  # shared_library("foo", 1)   #=> foo.1.dylib
+  # shared_library("foo", "*") #=> foo.2.dylib, foo.1.dylib, foo.dylib
+  # shared_library("*")        #=> foo.dylib, bar.dylib
+  # </pre>
+  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 == "*")
 
@@ -1675,6 +1683,8 @@ class Formula
     end
   end
 
+  # Returns the {PkgVersion} for this formula if it is installed.
+  # If not, return `nil`.
   def any_installed_version
     any_installed_keg&.version
   end
@@ -1981,7 +1991,8 @@ class Formula
   # has to be opened first.
   # <pre>system "./bootstrap.sh", "--arg1", "--prefix=#{prefix}"</pre>
   #
-  # For CMake we have some necessary defaults in {#std_cmake_args}:
+  # For CMake and other build systems we have some necessary defaults in e.g.
+  # {#std_cmake_args}:
   # <pre>system "cmake", ".", *std_cmake_args</pre>
   #
   # If the arguments given to `configure` (or `make` or `cmake`) are depending
@@ -2435,7 +2446,6 @@ class Formula
     #
     # <pre>bottle do
     #   root_url "https://example.com" # Optional root to calculate bottle URLs.
-    #   prefix "/opt/homebrew" # Optional HOMEBREW_PREFIX in which the bottles were built.
     #   cellar "/opt/homebrew/Cellar" # Optional HOMEBREW_CELLAR in which the bottles were built.
     #   rebuild 1 # Marks the old bottle as outdated without bumping the version/revision of the formula.
     #   sha256 "ef65c759c5097a36323fa9c77756468649e8d1980a3a4e05695c05e39568967c" => :catalina
@@ -2443,16 +2453,12 @@ class Formula
     #   sha256 "91dd0caca9bd3f38c439d5a7b6f68440c4274945615fae035ff0a369264b8a2f" => :high_sierra
     # end</pre>
     #
-    # Only formulae where the upstream URL breaks or moves frequently, require compiling
+    # Homebrew maintainers aim to bottle all formulae that require compilation.
-    # or have a reasonable amount of patches/resources should be bottled.
-    # Formulae which do not meet the above requirements should not be bottled.
     #
-    # Formulae which should not be bottled and can be installed without any compile
+    # Formulae that can be installed without compilation should be tagged with:
-    # required should be tagged with:
     # <pre>bottle :unneeded</pre>
     #
-    # Otherwise formulae which do not meet the above requirements and should not
+    # Formulae which should not be bottled should be tagged with:
-    # be bottled should be tagged with:
     # <pre>bottle :disable, "reasons"</pre>
     def bottle(*args, &block)
       stable.bottle(*args, &block)
@@ -2533,32 +2539,41 @@ class Formula
     end
 
     # The dependencies for this formula. Use strings for the names of other
-    # formulae. Homebrew provides some :special dependencies for stuff that
+    # formulae. Homebrew provides some `:special` {Requirement}s for stuff
-    # requires certain extra handling (often changing some ENV vars or
+    # that needs extra handling (often changing some ENV vars or
-    # deciding if to use the system provided version or not).
+    # deciding whether to use the system provided version).
-    # <pre># `:build` means this dep is only needed during build.
+    #
-    # depends_on "cmake" => :build</pre>
+    # `:build` means this dependency is only needed during build.
-    # <pre># `:recommended` dependencies are built by default.
+    # <pre>depends_on "cmake" => :build</pre>
-    # # But a `--without-...` option is generated to opt-out.
+    #
-    # depends_on "readline" => :recommended</pre>
+    # `:test` means this dependency is only needed during testing.
-    # <pre># `:optional` dependencies are NOT built by default unless the
+    # <pre>depends_on "node" => :test</pre>
-    # # auto-generated `--with-...` option is passed.
+    #
-    # depends_on "glib" => :optional</pre>
+    # `:recommended` dependencies are built by default.
-    # <pre># If you need to specify that another formula has to be built with/out
+    # But a `--without-...` option is generated to opt-out.
-    # # certain options (note, no `--` needed before the option):
+    # <pre>depends_on "readline" => :recommended</pre>
-    # depends_on "zeromq" => "with-pgm"
+    #
+    # `:optional` dependencies are NOT built by default unless the
+    # auto-generated `--with-...` option is passed.
+    # <pre>depends_on "glib" => :optional</pre>
+    #
+    # If you need to specify that another formula has to be built with/out
+    # certain options (note, no `--` needed before the option):
+    # <pre>depends_on "zeromq" => "with-pgm"
     # depends_on "qt" => ["with-qtdbus", "developer"] # Multiple options.</pre>
-    # <pre># Optional and enforce that "boost" is built with `--with-c++11`.
+    #
-    # depends_on "boost" => [:optional, "with-c++11"]</pre>
+    # Optional and enforce that "boost" is built with `--with-c++11`.
-    # <pre># If a dependency is only needed in certain cases:
+    # <pre>depends_on "boost" => [:optional, "with-c++11"]</pre>
-    # depends_on "sqlite" if MacOS.version >= :catalina
+    #
+    # If a dependency is only needed in certain cases:
+    # <pre>depends_on "sqlite" if MacOS.version >= :catalina
     # depends_on xcode: :build # If the formula really needs full Xcode to compile.
     # depends_on macos: :mojave # Needs at least macOS Mojave (10.14) to run.
-    # <pre># It is possible to only depend on something if
+    # </pre>
-    # # `build.with?` or `build.without? "another_formula"`:
+    #
-    # depends_on "postgresql" if build.without? "sqlite"</pre>
+    # It is possible to only depend on something if
-    # <pre># Require Python if `--with-python` is passed to `brew install example`:
+    # `build.with?` or `build.without? "another_formula"`:
-    # depends_on "python" => :optional</pre>
+    # <pre>depends_on "postgresql" if build.without? "sqlite"</pre>
     def depends_on(dep)
       specs.each { |spec| spec.depends_on(dep) }
     end
@@ -2659,6 +2674,13 @@ class Formula
       names.each { |name| conflicts << FormulaConflict.new(name, opts[:because]) }
     end
 
+    # Skip cleaning paths in a formula.
+    #
+    # Sometimes the formula {Cleaner cleaner} breaks things.
+    # Preserve cleaned paths with:
+    # <pre>skip_clean "bin/foo", "lib/bar"</pre>
+    # Keep .la files with:
+    # <pre>skip_clean :la</pre>
     def skip_clean(*paths)
       paths.flatten!
       # Specifying :all is deprecated and will become an error
@@ -2670,13 +2692,16 @@ class Formula
       @skip_clean_paths ||= Set.new
     end
 
-    # Software that will not be symlinked into the `brew --prefix` will only
+    # Software that will not be symlinked into the `brew --prefix` and will
-    # live in its Cellar. Other formulae can depend on it and then brew will
+    # only live in its Cellar. Other formulae can depend on it and Homebrew
-    # add the necessary includes and libs (etc.) during the brewing of that
+    # will add the necessary includes, libraries, and other paths while
-    # other formula. But generally, keg-only formulae are not in your PATH
+    # building that other formula.
-    # and not seen by compilers if you build your own software outside of
+    #
-    # Homebrew. This way, we don't shadow software provided by macOS.
+    # Keg-only formulae are not in your PATH and are not seen by compilers
+    # if you build your own software outside of Homebrew. This way, we
+    # don't shadow software provided by macOS.
     # <pre>keg_only :provided_by_macos</pre>
+    # <pre>keg_only :versioned_formulae</pre>
     # <pre>keg_only "because I want it so"</pre>
     def keg_only(reason, explanation = "")
       @keg_only_reason = KegOnlyReason.new(reason, explanation)
@@ -2712,6 +2737,15 @@ class Formula
       specs.each { |spec| spec.fails_with(compiler, &block) }
     end
 
+    # Marks the {Formula} as needing a certain standard, so Homebrew
+    # will fall back to other compilers if the default compiler
+    # does not implement that standard.
+    #
+    # We generally prefer to {.depends_on} a desired compiler and to
+    # explicitly use that compiler in a formula's {#install} block,
+    # rather than implicitly finding a suitable compiler with `needs`.
+    #
+    # @see #fails_with
     def needs(*standards)
       specs.each { |spec| spec.needs(*standards) }
     end
@@ -2749,9 +2783,9 @@ class Formula
     end
 
     # @!attribute [w] livecheck
-    # Livecheck can be used to check for newer versions of the software.
+    # {Livecheck} can be used to check for newer versions of the software.
     # This method evaluates the DSL specified in the livecheck block of the
-    # {Formula} (if it exists) and sets the instance variables of a Livecheck
+    # {Formula} (if it exists) and sets the instance variables of a {Livecheck}
     # object accordingly. This is used by `brew livecheck` to check for newer
     # versions of the software.
     #
@@ -2790,6 +2824,8 @@ class Formula
     # will not be deprecated.
     # <pre>deprecate! date: "2020-08-27", because: :unmaintained</pre>
     # <pre>deprecate! date: "2020-08-27", because: "has been replaced by foo"</pre>
+    # @see https://docs.brew.sh/Deprecating-Disabling-and-Removing-Formulae
+    # @see DeprecateDisable::DEPRECATE_DISABLE_REASONS
     def deprecate!(date: nil, because: nil)
       odeprecated "`deprecate!` without a reason", "`deprecate! because: \"reason\"`" if because.blank?
       odeprecated "`deprecate!` without a date", "`deprecate! date: \"#{Date.today}\"`" if date.blank?
@@ -2805,6 +2841,7 @@ class Formula
     # Whether this {Formula} is deprecated (i.e. warns on installation).
     # Defaults to false.
     # @return [Boolean]
+    # @see .deprecate!
     def deprecated?
       @deprecated == true
     end
@@ -2812,18 +2849,22 @@ class Formula
     # The date that this {Formula} was or becomes deprecated.
     # Returns `nil` if no date is specified.
     # @return Date
+    # @see .deprecate!
     attr_reader :deprecation_date
 
     # The reason for deprecation of a {Formula}.
     # @return [nil] if no reason was provided or the formula is not deprecated.
     # @return [String, Symbol]
+    # @see .deprecate!
     attr_reader :deprecation_reason
 
-    # Disables a {Formula}  (on a given date, if provided) so it cannot be
+    # Disables a {Formula} (on a given date, if provided) so it cannot be
     # installed. If the date has not yet passed the formula
     # will be deprecated instead of disabled.
     # <pre>disable! date: "2020-08-27", because: :does_not_build</pre>
     # <pre>disable! date: "2020-08-27", because: "has been replaced by foo"</pre>
+    # @see https://docs.brew.sh/Deprecating-Disabling-and-Removing-Formulae
+    # @see DeprecateDisable::DEPRECATE_DISABLE_REASONS
     def disable!(date: nil, because: nil)
       odeprecated "`disable!` without a reason", "`disable! because: \"reason\"`" if because.blank?
       odeprecated "`disable!` without a date", "`disable! date: \"#{Date.today}\"`" if date.blank?
@@ -2843,6 +2884,7 @@ class Formula
     # Whether this {Formula} is disabled (i.e. cannot be installed).
     # Defaults to false.
     # @return [Boolean]
+    # @see .disable!
     def disabled?
       @disabled == true
     end
@@ -2850,14 +2892,21 @@ class Formula
     # The date that this {Formula} was or becomes disabled.
     # Returns `nil` if no date is specified.
     # @return Date
+    # @see .disable!
     attr_reader :disable_date
 
     # The reason this {Formula} is disabled.
     # Returns `nil` if no reason was provided or the formula is not disabled.
     # @return [String, Symbol]
+    # @see .disable!
     attr_reader :disable_reason
 
-    # @private
+    # Permit overwriting certain files while linking.
+    #
+    # Sometimes we accidentally install files outside prefix. Once we fix that,
+    # users will get a link conflict error. Overwrite those files with:
+    # <pre>link_overwrite "bin/foo", "lib/bar"</pre>
+    # <pre>link_overwrite "share/man/man1/baz-*"</pre>
     def link_overwrite(*paths)
       paths.flatten!
       link_overwrite_paths.merge(paths)
@@ -2868,6 +2917,7 @@ class Formula
       @link_overwrite_paths ||= Set.new
     end
 
+    # Permit links to certain libraries that don't exist. Available on Linux only.
     def ignore_missing_libraries(*)
       raise FormulaSpecificationError, "#{__method__} is available on Linux only"
     end

Library/Homebrew/utils/inreplace.rb

@@ -23,14 +23,22 @@ module Utils
     module_function
 
     # Sometimes we have to change a bit before we install. Mostly we
-    # prefer a patch but if you need the `prefix` of this formula in the
+    # prefer a patch, but if you need the {Formula#prefix prefix} of
-    # patch you have to resort to `inreplace`, because in the patch
+    # this formula in the patch you have to resort to `inreplace`,
-    # you don't have access to any var defined by the formula. Only
+    # because in the patch you don't have access to any variables
-    # `HOMEBREW_PREFIX` is available in the embedded patch.
+    # defined by the formula, as only `HOMEBREW_PREFIX` is available
+    # in the {DATAPatch embedded patch}.
     #
     # `inreplace` supports regular expressions:
     # <pre>inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"</pre>
     #
+    # `inreplace` supports blocks:
+    # <pre>inreplace "Makefile" do |s|
+    #   s.gsub! "/usr/local", HOMEBREW_PREFIX.to_s
+    # end
+    # </pre>
+    #
+    # @see StringInreplaceExtension
     # @api public
     sig do
       params(
@@ -65,6 +73,7 @@ module Utils
       raise Error, errors unless errors.empty?
     end
 
+    # @api private
     def inreplace_pairs(path, replacement_pairs, read_only_run: false, silent: false)
       str = File.open(path, "rb", &:read) || ""
       contents = StringInreplaceExtension.new(str)

docs/Bottles.md

@@ -33,7 +33,6 @@ A full example:
 ```ruby
 bottle do
   root_url "https://example.com"
-  prefix "/opt/homebrew"
   cellar "/opt/homebrew/Cellar"
   rebuild 4
   sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :sierra
@@ -50,10 +49,6 @@ By default this is omitted and the Homebrew default bottle URL root is used. Thi
 Optionally contains the value of `HOMEBREW_CELLAR` in which the bottles were built.
 Most compiled software contains references to its compiled location so cannot be simply relocated anywhere on disk. If this value is `:any` or `:any_skip_relocation` this means that the bottle can be safely installed in any Cellar as it did not contain any references to its installation Cellar. This can be omitted if a bottle is compiled (as all default Homebrew ones are) for the default `HOMEBREW_CELLAR` of `/usr/local/Cellar`.
 
-### Prefix (`prefix`)
-Optionally contains the value of `HOMEBREW_PREFIX` in which the bottles were built.
-See description of `cellar`. When `cellar` is `:any` or `:any_skip_relocation` the prefix should be omitted.
-
 ### Rebuild version (`rebuild`)
 Optionally contains the rebuild version of the bottle.
 Sometimes bottles may need be updated without bumping the version of the formula, e.g. a new patch was applied. In that case the rebuild will have a value of 1 or more.