More API documentation.

And remove the documented stuff from the `example-formula.rb`.

Closes Homebrew/homebrew#43241.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>

5 files changed, 106 insertions, 24 deletions

diff --git a/Library/Homebrew/extend/ENV/shared.rb b/Library/Homebrew/extend/ENV/shared.rb
index a85eff305..7553540c9 100644
--- a/Library/Homebrew/extend/ENV/shared.rb
+++ b/Library/Homebrew/extend/ENV/shared.rb
@@ -1,12 +1,20 @@
 require "formula"
 require "compilers"
 
+# Homebrew extends Ruby's `ENV` to make our code more readable.
+# Implemented in {SharedEnvExtension} and either {Superenv} or
+# {Stdenv} (depending on the build mode).
+# @see Superenv
+# @see Stdenv
+# @see http://www.rubydoc.info/stdlib/Env Ruby's ENV API
 module SharedEnvExtension
   include CompilerConstants
 
+  # @private
   CC_FLAG_VARS = %w[CFLAGS CXXFLAGS OBJCFLAGS OBJCXXFLAGS]
+  # @private
   FC_FLAG_VARS = %w[FCFLAGS FFLAGS]
-
+  # @private
   SANITIZED_VARS = %w[
     CDPATH GREP_OPTIONS CLICOLOR_FORCE
     CPATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH OBJC_INCLUDE_PATH
@@ -18,11 +26,13 @@ module SharedEnvExtension
     LIBRARY_PATH
   ]
 
+  # @private
   def setup_build_environment(formula = nil)
     @formula = formula
     reset
   end
 
+  # @private
   def reset
     SANITIZED_VARS.each { |k| delete(k) }
   end
@@ -72,6 +82,10 @@ module SharedEnvExtension
     append key, path, File::PATH_SEPARATOR if File.directory? path
   end
 
+  # Prepends a directory to `PATH`.
+  # Is the formula struggling to find the pkgconfig file? Point it to it.
+  # This is done automatically for `keg_only` formulae.
+  # <pre>ENV.prepend_path "PKG_CONFIG_PATH", "#{Formula["glib"].opt_lib}/pkgconfig"</pre>
   def prepend_path(key, path)
     prepend key, path, File::PATH_SEPARATOR if File.directory? path
   end
@@ -126,6 +140,13 @@ module SharedEnvExtension
     self["FCFLAGS"]
   end
 
+  # Outputs the current compiler.
+  # @return [Symbol]
+  # <pre># Do something only for clang
+  # if ENV.compiler == :clang
+  #   # modify CFLAGS CXXFLAGS OBJCFLAGS OBJCXXFLAGS in one go:
+  #   ENV.append_to_cflags "-I ./missing/includes"
+  # end</pre>
   def compiler
     @compiler ||= if (cc = ARGV.cc)
       warn_about_non_apple_gcc($&) if cc =~ GNU_GCC_REGEXP
@@ -147,6 +168,7 @@ module SharedEnvExtension
     end
   end
 
+  # @private
   def determine_cc
     COMPILER_SYMBOL_MAP.invert.fetch(compiler, compiler)
   end
@@ -159,13 +181,14 @@ module SharedEnvExtension
     end
   end
 
-  # Snow Leopard defines an NCURSES value the opposite of most distros
+  # Snow Leopard defines an NCURSES value the opposite of most distros.
   # See: https://bugs.python.org/issue6848
-  # Currently only used by aalib in core
+  # Currently only used by aalib in core.
   def ncurses_define
     append "CPPFLAGS", "-DNCURSES_OPAQUE=0"
   end
 
+  # @private
   def userpaths!
     paths = ORIGINAL_PATHS.map { |p| p.realpath.to_s rescue nil } - %w[/usr/X11/bin /opt/X11/bin]
     self["PATH"] = paths.unshift(*self["PATH"].split(File::PATH_SEPARATOR)).uniq.join(File::PATH_SEPARATOR)
@@ -212,12 +235,14 @@ module SharedEnvExtension
   end
 
   # ld64 is a newer linker provided for Xcode 2.5
+  # @private
   def ld64
     ld64 = Formulary.factory("ld64")
     self["LD"] = ld64.bin/"ld"
     append "LDFLAGS", "-B#{ld64.bin}/"
   end
 
+  # @private
   def gcc_version_formula(name)
     version = name[GNU_GCC_REGEXP, 1]
     gcc_version_name = "gcc#{version.delete(".")}"
@@ -230,6 +255,7 @@ module SharedEnvExtension
     end
   end
 
+  # @private
   def warn_about_non_apple_gcc(name)
     begin
       gcc_formula = gcc_version_formula(name)
diff --git a/Library/Homebrew/extend/ENV/std.rb b/Library/Homebrew/extend/ENV/std.rb
index d05ccf1a3..fef991540 100644
--- a/Library/Homebrew/extend/ENV/std.rb
+++ b/Library/Homebrew/extend/ENV/std.rb
@@ -2,9 +2,11 @@ require "hardware"
 require "os/mac"
 require "extend/ENV/shared"
 
+# @deprecated
 module Stdenv
   include SharedEnvExtension
 
+  # @private
   SAFE_CFLAGS_FLAGS = "-w -pipe"
   DEFAULT_FLAGS = "-march=core2 -msse4"
 
@@ -14,6 +16,7 @@ module Stdenv
     end
   end
 
+  # @private
   def setup_build_environment(formula = nil)
     super
 
@@ -69,6 +72,7 @@ module Stdenv
     end
   end
 
+  # @private
   def determine_pkg_config_libdir
     paths = []
     paths << "#{HOMEBREW_PREFIX}/lib/pkgconfig"
@@ -106,11 +110,13 @@ module Stdenv
     end
   end
 
+  # @private
   def determine_cc
     s = super
     MacOS.locate(s) || Pathname.new(s)
   end
 
+  # @private
   def determine_cxx
     dir, base = determine_cc.split
     dir / base.to_s.sub("gcc", "g++").sub("clang", "clang++")
@@ -295,6 +301,7 @@ module Stdenv
     end
   end
 
+  # @private
   def replace_in_cflags(before, after)
     CC_FLAG_VARS.each do |key|
       self[key] = self[key].sub(before, after) if key?(key)
@@ -308,6 +315,7 @@ module Stdenv
 
   # Sets architecture-specific flags for every environment variable
   # given in the list `flags`.
+  # @private
   def set_cpu_flags(flags, default = DEFAULT_FLAGS, map = Hardware::CPU.optimization_flags)
     cflags =~ /(-Xarch_#{Hardware::CPU.arch_32_bit} )-march=/
     xarch = $1.to_s
@@ -319,6 +327,7 @@ module Stdenv
     append flags, map.fetch(effective_arch, default)
   end
 
+  # @private
   def effective_arch
     if ARGV.build_bottle?
       ARGV.bottle_arch || Hardware.oldest_cpu
@@ -332,6 +341,7 @@ module Stdenv
     end
   end
 
+  # @private
   def set_cpu_cflags(default = DEFAULT_FLAGS, map = Hardware::CPU.optimization_flags)
     set_cpu_flags CC_FLAG_VARS, default, map
   end
@@ -346,5 +356,6 @@ module Stdenv
   end
 
   # This method does nothing in stdenv since there's no arg refurbishment
+  # @private
   def refurbish_args; end
 end
diff --git a/Library/Homebrew/extend/ENV/super.rb b/Library/Homebrew/extend/ENV/super.rb
index 95a8773cd..5216b579c 100644
--- a/Library/Homebrew/extend/ENV/super.rb
+++ b/Library/Homebrew/extend/ENV/super.rb
@@ -1,20 +1,23 @@
 require "os/mac"
 require "extend/ENV/shared"
 
-### Why `superenv`?
-# 1) Only specify the environment we need (NO LDFLAGS for cmake)
-# 2) Only apply compiler specific options when we are calling that compiler
-# 3) Force all incpaths and libpaths into the cc instantiation (less bugs)
-# 4) Cater toolchain usage to specific Xcode versions
-# 5) Remove flags that we don't want or that will break builds
-# 6) Simpler code
-# 7) Simpler formula that *just work*
-# 8) Build-system agnostic configuration of the tool-chain
-
+# ### Why `superenv`?
+#
+# 1. Only specify the environment we need (NO LDFLAGS for cmake)
+# 2. Only apply compiler specific options when we are calling that compiler
+# 3. Force all incpaths and libpaths into the cc instantiation (less bugs)
+# 4. Cater toolchain usage to specific Xcode versions
+# 5. Remove flags that we don't want or that will break builds
+# 6. Simpler code
+# 7. Simpler formula that *just work*
+# 8. Build-system agnostic configuration of the tool-chain
 module Superenv
   include SharedEnvExtension
 
-  attr_accessor :keg_only_deps, :deps, :x11
+  # @private
+  attr_accessor :keg_only_deps, :deps
+
+  attr_accessor :x11
   alias_method :x11?, :x11
 
   def self.extended(base)
@@ -22,6 +25,7 @@ module Superenv
     base.deps = []
   end
 
+  # @private
   def self.bin
     return unless MacOS.has_apple_developer_tools?
 
@@ -36,6 +40,7 @@ module Superenv
     delete("as_nl")
   end
 
+  # @private
   def setup_build_environment(formula = nil)
     super
     send(compiler)
@@ -302,6 +307,7 @@ module Superenv
     append "HOMEBREW_CCCFG", "h", "" if compiler == :clang
   end
 
+  # @private
   def refurbish_args
     append "HOMEBREW_CCCFG", "O", ""
   end
@@ -312,6 +318,7 @@ module Superenv
     end
   end
 
+  # @private
   def noop(*_args); end
   noops = []
 
diff --git a/Library/Homebrew/extend/fileutils.rb b/Library/Homebrew/extend/fileutils.rb
index 741fca57f..a6321931c 100644
--- a/Library/Homebrew/extend/fileutils.rb
+++ b/Library/Homebrew/extend/fileutils.rb
@@ -1,7 +1,8 @@
 require "fileutils"
 require "tmpdir"
 
-# We enhance FileUtils to make our Formula code more readable.
+# Homebrew extends Ruby's `FileUtils` to make our code more readable.
+# @see http://ruby-doc.org/stdlib-1.8.7/libdoc/fileutils/rdoc/FileUtils.html Ruby's FileUtils API
 module FileUtils
   # Create a temporary directory then yield. When the block returns,
   # recursively delete the temporary directory.
@@ -23,8 +24,10 @@ module FileUtils
   end
   module_function :mktemp
 
-  # A version of mkdir that also changes to that folder in a block.
+  # @private
   alias_method :old_mkdir, :mkdir
+
+  # A version of mkdir that also changes to that folder in a block.
   def mkdir(name, &_block)
     old_mkdir(name)
     if block_given?
@@ -42,6 +45,7 @@ module FileUtils
   # never backported into the 1.9.3 branch. Fixed in 2.0.0.
   # The monkey-patched method here is copied directly from upstream fix.
   if RUBY_VERSION < "2.0.0"
+    # @private
     class Entry_
       alias_method :old_copy_metadata, :copy_metadata
       def copy_metadata(path)
@@ -82,23 +86,27 @@ module FileUtils
     end
   end
 
-  private
-
-  # Run scons using a Homebrew-installed version, instead of whatever
-  # is in the user's PATH
+  # Run `scons` using a Homebrew-installed version rather than whatever is in the `PATH`.
   def scons(*args)
     system Formulary.factory("scons").opt_bin/"scons", *args
   end
 
+  # Run the `rake` from the `ruby` Homebrew is using rather than whatever is in the `PATH`.
   def rake(*args)
     system RUBY_BIN/"rake", *args
   end
 
-  alias_method :old_ruby, :ruby if method_defined?(:ruby)
+  if method_defined?(:ruby)
+    # @private
+    alias_method :old_ruby, :ruby
+  end
+
+  # Run the `ruby` Homebrew is using rather than whatever is in the `PATH`.
   def ruby(*args)
     system RUBY_PATH, *args
   end
 
+  # Run `xcodebuild` without Homebrew's compiler environment variables set.
   def xcodebuild(*args)
     removed = ENV.remove_cc_etc
     system "xcodebuild", *args
diff --git a/Library/Homebrew/extend/pathname.rb b/Library/Homebrew/extend/pathname.rb
index c71a636e9..ed831f2cb 100644
--- a/Library/Homebrew/extend/pathname.rb
+++ b/Library/Homebrew/extend/pathname.rb
@@ -3,12 +3,15 @@ require "mach"
 require "resource"
 require "metafiles"
 
-# we enhance pathname to make our code more readable
+# Homebrew extends Ruby's `Pathname` to make our code more readable.
+# @see http://ruby-doc.org/stdlib-1.8.7/libdoc/pathname/rdoc/Pathname.html  Ruby's Pathname API
 class Pathname
   include MachO
 
+  # @private
   BOTTLE_EXTNAME_RX = /(\.[a-z0-9_]+\.bottle\.(\d+\.)?tar\.gz)$/
 
+  # Moves a file from the original location to the {Pathname}'s.
   def install(*sources)
     sources.each do |src|
       case src
@@ -77,8 +80,12 @@ class Pathname
   end
   private :install_symlink_p
 
+  if method_defined?(:write)
+    # @private
+    alias_method :old_write, :write
+  end
+
   # we assume this pathname object is a file obviously
-  alias_method :old_write, :write if method_defined?(:write)
   def write(content, *open_args)
     raise "Will not overwrite #{self}" if exist?
     dirname.mkpath
@@ -131,6 +138,7 @@ class Pathname
   end
   private :default_stat
 
+  # @private
   def cp(dst)
     opoo "Pathname#cp is deprecated, use FileUtils.cp"
     if file?
@@ -141,6 +149,7 @@ class Pathname
     dst
   end
 
+  # @private
   def cp_path_sub(pattern, replacement)
     raise "#{self} does not exist" unless self.exist?
 
@@ -157,8 +166,10 @@ class Pathname
     end
   end
 
-  # extended to support common double extensions
+  # @private
   alias_method :extname_old, :extname
+
+  # extended to support common double extensions
   def extname(path = to_s)
     BOTTLE_EXTNAME_RX.match(path)
     return $1 if $1
@@ -175,6 +186,7 @@ class Pathname
   # I don't trust the children.length == 0 check particularly, not to mention
   # it is slow to enumerate the whole directory just to see if it is empty,
   # instead rely on good ol' libc and the filesystem
+  # @private
   def rmdir_if_possible
     rmdir
     true
@@ -189,17 +201,20 @@ class Pathname
     false
   end
 
+  # @private
   def chmod_R(perms)
     opoo "Pathname#chmod_R is deprecated, use FileUtils.chmod_R"
     require "fileutils"
     FileUtils.chmod_R perms, to_s
   end
 
+  # @private
   def version
     require "version"
     Version.parse(self)
   end
 
+  # @private
   def compression_type
     case extname
     when ".jar", ".war"
@@ -240,10 +255,12 @@ class Pathname
     end
   end
 
+  # @private
   def text_executable?
     /^#!\s*\S+/ === open("r") { |f| f.read(1024) }
   end
 
+  # @private
   def incremental_hash(klass)
     digest = klass.new
     if digest.respond_to?(:file)
@@ -255,6 +272,7 @@ class Pathname
     digest.hexdigest
   end
 
+  # @private
   def sha1
     require "digest/sha1"
     incremental_hash(Digest::SHA1)
@@ -282,10 +300,12 @@ class Pathname
     children.select(&:directory?)
   end
 
+  # @private
   def resolved_path
     self.symlink? ? dirname+readlink : self
   end
 
+  # @private
   def resolved_path_exists?
     link = readlink
   rescue ArgumentError
@@ -295,6 +315,7 @@ class Pathname
     (dirname+link).exist?
   end
 
+  # @private
   def make_relative_symlink(src)
     dirname.mkpath
     File.symlink(src.relative_path_from(dirname), self)
@@ -308,6 +329,7 @@ class Pathname
     self + other.to_s
   end unless method_defined?(:/)
 
+  # @private
   def ensure_writable
     saved_perms = nil
     unless writable_real?
@@ -319,10 +341,12 @@ class Pathname
     chmod saved_perms if saved_perms
   end
 
+  # @private
   def install_info
     quiet_system "/usr/bin/install-info", "--quiet", to_s, "#{dirname}/dir"
   end
 
+  # @private
   def uninstall_info
     quiet_system "/usr/bin/install-info", "--delete", "--quiet", to_s, "#{dirname}/dir"
   end
@@ -389,6 +413,7 @@ class Pathname
     end
   end
 
+  # @private
   def abv
     out = ""
     n = Utils.popen_read("find", expand_path.to_s, "-type", "f", "!", "-name", ".DS_Store").split("\n").size
@@ -403,7 +428,9 @@ class Pathname
   # the Regexp literals, which forces string interpolation to happen only
   # once instead of each time the method is called. This is fixed in 1.9+.
   if RUBY_VERSION <= "1.8.7"
+    # @private
     alias_method :old_chop_basename, :chop_basename
+
     def chop_basename(path)
       base = File.basename(path)
       if /\A#{Pathname::SEPARATOR_PAT}?\z/o =~ base
@@ -414,7 +441,9 @@ class Pathname
     end
     private :chop_basename
 
+    # @private
     alias_method :old_prepend_prefix, :prepend_prefix
+
     def prepend_prefix(prefix, relpath)
       if relpath.empty?
         File.dirname(prefix)
@@ -437,6 +466,7 @@ class Pathname
   end
 end
 
+# @private
 module ObserverPathnameExtension
   class << self
     attr_accessor :n, :d