Make some global variables part of the public API

These are all useful to be able to tell users to rely on them and
we've used them long enough for it to make sense as a public API.

Relatedly, these are all used in at least some Homebrew/homebrew-core
or Homebrew/homebrew-cask formulae.

While we're here, update the descriptions to be a bit more user
friendly.

Author: MikeMcQuaid

Library/Homebrew/.rubocop.yml

@@ -65,6 +65,7 @@ Style/Documentation:
     - livecheck/strategy/yaml.rb
     - os.rb
     - resource.rb
+    - startup/config.rb
     - utils/inreplace.rb
     - utils/shebang.rb
     - utils/string_inreplace_extension.rb

Library/Homebrew/startup/config.rb

@@ -3,17 +3,39 @@
 
 raise "HOMEBREW_BREW_FILE was not exported! Please call bin/brew directly!" unless ENV["HOMEBREW_BREW_FILE"]
 
-# Path to `bin/brew` main executable in `HOMEBREW_PREFIX`
-# Used for e.g. permissions checks.
-HOMEBREW_ORIGINAL_BREW_FILE = Pathname(ENV.fetch("HOMEBREW_ORIGINAL_BREW_FILE")).freeze
-
-# Path to the executable that should be used to run `brew`.
-# This may be HOMEBREW_ORIGINAL_BREW_FILE or HOMEBREW_BREW_WRAPPER.
+# The path to the executable that should be used to run `brew`.
+# This may be HOMEBREW_ORIGINAL_BREW_FILE or HOMEBREW_BREW_WRAPPER depending on
+# the system configuration. Favour this instead of running `brew` and expecting
+# it to be in the `PATH`.
+# @api public
 HOMEBREW_BREW_FILE = Pathname(ENV.fetch("HOMEBREW_BREW_FILE")).freeze
 
-# Where we link under
+# Where Homebrew is installed and files are linked to.
+# @api public
 HOMEBREW_PREFIX = Pathname(ENV.fetch("HOMEBREW_PREFIX")).freeze
 
+# Where Homebrew stores built formulae packages, linking (non-keg-only) ones
+# back to `HOMEBREW_PREFIX`.
+# @api public
+HOMEBREW_CELLAR = Pathname(ENV.fetch("HOMEBREW_CELLAR")).freeze
+
+# Where Homebrew downloads (bottles, source tarballs, casks etc.) are cached.
+# @api public
+HOMEBREW_CACHE = Pathname(ENV.fetch("HOMEBREW_CACHE")).freeze
+
+# Where Homebrew stores temporary files.
+# We use `/tmp` instead of `TMPDIR` because long paths break Unix domain
+# sockets.
+# @api public
+HOMEBREW_TEMP = Pathname(ENV.fetch("HOMEBREW_TEMP")).then do |tmp|
+  tmp.mkpath unless tmp.exist?
+  tmp.realpath
+end.freeze
+
+# Path to `bin/brew` main executable in `HOMEBREW_PREFIX`
+# Used for e.g. permissions checks.
+HOMEBREW_ORIGINAL_BREW_FILE = Pathname(ENV.fetch("HOMEBREW_ORIGINAL_BREW_FILE")).freeze
+
 # Where `.git` is found
 HOMEBREW_REPOSITORY = Pathname(ENV.fetch("HOMEBREW_REPOSITORY")).freeze
 
@@ -35,27 +57,15 @@
 # Where we store lock files
 HOMEBREW_LOCKS = (HOMEBREW_PREFIX/"var/homebrew/locks").freeze
 
-# Where we store built products
-HOMEBREW_CELLAR = Pathname(ENV.fetch("HOMEBREW_CELLAR")).freeze
-
 # Where we store Casks
 HOMEBREW_CASKROOM = Pathname(ENV.fetch("HOMEBREW_CASKROOM")).freeze
 
-# Where downloads (bottles, source tarballs, etc.) are cached
-HOMEBREW_CACHE = Pathname(ENV.fetch("HOMEBREW_CACHE")).freeze
-
 # Where formulae installed via URL are cached
 HOMEBREW_CACHE_FORMULA = (HOMEBREW_CACHE/"Formula").freeze
 
 # Where build, postinstall and test logs of formulae are written to
 HOMEBREW_LOGS = Pathname(ENV.fetch("HOMEBREW_LOGS")).expand_path.freeze
 
-# Must use `/tmp` instead of `TMPDIR` because long paths break Unix domain sockets
-HOMEBREW_TEMP = Pathname(ENV.fetch("HOMEBREW_TEMP")).then do |tmp|
-  tmp.mkpath unless tmp.exist?
-  tmp.realpath
-end.freeze
-
 # Where installed taps live
 HOMEBREW_TAP_DIRECTORY = (HOMEBREW_LIBRARY/"Taps").freeze