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>

.yardopts

@@ -7,7 +7,7 @@
 --exclude Library/Homebrew/compat/
 Library/Homebrew/**/*.rb
 -
+share/doc/homebrew/*.html
 Library/Homebrew/*.md
-Library/Homebrew/manpages/*.md
 share/doc/homebrew/*.md
 *.md

Library/Homebrew/README.md

-# Homebrew Public API
-We're (finally) working on a documented public API for Homebrew. It's currently a work in progress; a bunch of public stuff is documented and a bunch of private stuff is undocumented. Sorry about that!
+# Homebrew's Formula API
+This is the (partially) documented public API for Homebrew. It's currently a work in progress. Sorry about that!
 
-The main class you should look at is {Formula}. Assume everything else is private for now.
+The main class you should look at is the {Formula} class (and classes linked from there). That's the class that's used to create Homebrew formulae (i.e. package descriptions). Assume anything else you stumble upon is private.
+
+You may also find the [Formula Cookbook](Formula-Cookbook.md) and [Ruby Style Guide](https://github.com/styleguide/ruby) helpful in creating formulae.
+
+Good luck!

Library/Homebrew/build_options.rb

 class BuildOptions
+  # @private
   def initialize(args, options)
     @args = args
     @options = options
   end
 
+  # True if a {Formula} is being built with a specific option
+  # (which isn't named `with-*` or `without-*`).
+  # @deprecated
   def include?(name)
     @args.include?("--#{name}")
   end
 
+  # True if a {Formula} is being built with a specific option.
+  # <pre>args << "--i-want-spam" if build.with? "spam"
+  #
+  # args << "--qt-gui" if build.with? "qt" # "--with-qt" ==> build.with? "qt"
+  #
+  # # If a formula presents a user with a choice, but the choice must be fulfilled:
+  # if build.with? "example2"
+  #   args << "--with-example2"
+  # else
+  #   args << "--with-example1"
+  # end</pre>
   def with?(val)
     name = val.respond_to?(:option_name) ? val.option_name : val
 
@@ -20,47 +35,65 @@ class BuildOptions
     end
   end
 
+  # True if a {Formula} is being built without a specific option.
+  # <pre>args << "--no-spam-plz" if build.without? "spam"
   def without?(name)
     !with? name
   end
 
+  # True if a {Formula} is being built as a bottle (i.e. binary package).
   def bottle?
     include? "build-bottle"
   end
 
+  # True if a {Formula} is being built with {Formula.head} instead of {Formula.stable}.
+  # <pre>args << "--some-new-stuff" if build.head?</pre>
+  # <pre># If there are multiple conditional arguments use a block instead of lines.
+  #  if build.head?
+  #    args << "--i-want-pizza"
+  #    args << "--and-a-cold-beer" if build.with? "cold-beer"
+  #  end</pre>
   def head?
     include? "HEAD"
   end
 
+  # True if a {Formula} is being built with {Formula.devel} instead of {Formula.stable}.
+  # <pre>args << "--some-beta" if build.devel?</pre>
   def devel?
     include? "devel"
   end
 
+  # True if a {Formula} is being built with {Formula.stable} instead of {Formula.devel} or {Formula.head}. This is the default.
+  # <pre>args << "--some-beta" if build.devel?</pre>
   def stable?
     !(head? || devel?)
   end
 
-  # True if the user requested a universal build.
+  # True if a {Formula} is being built universally.
+  # e.g. on newer Intel Macs this means a combined x86_64/x86 binary/library.
+  # <pre>args << "--universal-binary" if build.universal?</pre>
   def universal?
     include?("universal") && option_defined?("universal")
   end
 
-  # True if the user requested to enable C++11 mode.
+  # True if a {Formula} is being built in C++11 mode.
   def cxx11?
     include?("c++11") && option_defined?("c++11")
   end
 
-  # Request a 32-bit only build.
+  # True if a {Formula} is being built in 32-bit/x86 mode.
   # This is needed for some use-cases though we prefer to build Universal
   # when a 32-bit version is needed.
   def build_32_bit?
     include?("32-bit") && option_defined?("32-bit")
   end
 
+  # @private
   def used_options
     @options & @args
   end
 
+  # @private
   def unused_options
     @options - @args
   end

Library/Homebrew/cmd/create.rb

@@ -118,7 +118,7 @@ class FormulaCreator
 
   def template; <<-EOS.undent
     # Documentation: https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md
-    #                #{HOMEBREW_CONTRIB}/example-formula.rb
+    #                http://www.rubydoc.info/github/Homebrew/homebrew/master/frames
     # PLEASE REMOVE ALL GENERATED COMMENTS BEFORE SUBMITTING YOUR PULL REQUEST!
 
     class #{Formulary.class_s(name)} < Formula

Library/Homebrew/cmd/man.rb

@@ -3,6 +3,7 @@ require "formula"
 module Homebrew
   SOURCE_PATH=HOMEBREW_REPOSITORY/"Library/Homebrew/manpages"
   TARGET_PATH=HOMEBREW_REPOSITORY/"share/man/man1"
+  DOC_PATH=HOMEBREW_REPOSITORY/"share/doc/homebrew"
   LINKED_PATH=HOMEBREW_PREFIX/"share/man/man1"
 
   def man
@@ -21,12 +22,15 @@ module Homebrew
     else
       Homebrew.install_gem_setup_path! "ronn"
 
+      puts "Writing HTML fragments to #{DOC_PATH}"
       puts "Writing manpages to #{TARGET_PATH}"
 
       target_file = nil
       Dir["#{SOURCE_PATH}/*.md"].each do |source_file|
-        target_file = TARGET_PATH/File.basename(source_file, ".md")
-        safe_system "ronn --roff --pipe --organization='Homebrew' --manual='brew' #{source_file} > #{target_file}"
+        target_html = DOC_PATH/"#{File.basename(source_file, ".md")}.html"
+        safe_system "ronn --fragment --pipe --organization='Homebrew' --manual='brew' #{source_file} > #{target_html}"
+        target_man = TARGET_PATH/File.basename(source_file, ".md")
+        safe_system "ronn --roff --pipe --organization='Homebrew' --manual='brew' #{source_file} > #{target_man}"
       end
 
       system "man", target_file if ARGV.flag? "--verbose"

Library/Homebrew/compilers.rb

+# @private
 module CompilerConstants
   GNU_GCC_VERSIONS = %w[4.3 4.4 4.5 4.6 4.7 4.8 4.9 5]
   GNU_GCC_REGEXP = /^gcc-(4\.[3-9]|5)$/

Library/Homebrew/extend/ENV/shared.rb

 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)

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

Library/Homebrew/extend/ENV/super.rb

 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 = []
 

Library/Homebrew/extend/fileutils.rb

 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

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

Library/Homebrew/mach.rb

 module ArchitectureListExtension
+  # @private
   def fat?
     length > 1
   end
 
+  # @private
   def intel_universal?
     intersects_all?(Hardware::CPU::INTEL_32BIT_ARCHS, Hardware::CPU::INTEL_64BIT_ARCHS)
   end
 
+  # @private
   def ppc_universal?
     intersects_all?(Hardware::CPU::PPC_32BIT_ARCHS, Hardware::CPU::PPC_64BIT_ARCHS)
   end
 
   # Old-style 32-bit PPC/Intel universal, e.g. ppc7400 and i386
+  # @private
   def cross_universal?
     intersects_all?(Hardware::CPU::PPC_32BIT_ARCHS, Hardware::CPU::INTEL_32BIT_ARCHS)
   end
 
+  # @private
   def universal?
     intel_universal? || ppc_universal? || cross_universal?
   end
@@ -24,6 +29,7 @@ module ArchitectureListExtension
     (Hardware::CPU::PPC_32BIT_ARCHS+Hardware::CPU::PPC_64BIT_ARCHS).any? { |a| self.include? a }
   end
 
+  # @private
   def remove_ppc!
     (Hardware::CPU::PPC_32BIT_ARCHS+Hardware::CPU::PPC_64BIT_ARCHS).each { |a| delete a }
   end
@@ -46,12 +52,13 @@ module ArchitectureListExtension
 end
 
 module MachO
+  # @private
   OTOOL_RX = /\t(.*) \(compatibility version (?:\d+\.)*\d+, current version (?:\d+\.)*\d+\)/
 
   # Mach-O binary methods, see:
   # /usr/include/mach-o/loader.h
   # /usr/include/mach-o/fat.h
-
+  # @private
   def mach_data
     @mach_data ||= begin
       offsets = []
@@ -132,18 +139,22 @@ module MachO
     arch == :ppc64
   end
 
+  # @private
   def dylib?
     mach_data.any? { |m| m.fetch(:type) == :dylib }
   end
 
+  # @private
   def mach_o_executable?
     mach_data.any? { |m| m.fetch(:type) == :executable }
   end
 
+  # @private
   def mach_o_bundle?
     mach_data.any? { |m| m.fetch(:type) == :bundle }
   end
 
+  # @private
   class Metadata
     attr_reader :path, :dylib_id, :dylibs
 
@@ -171,6 +182,7 @@ module MachO
     end
   end
 
+  # @private
   def mach_metadata
     @mach_metadata ||= Metadata.new(self)
   end
@@ -180,10 +192,12 @@ module MachO
   # to be absolute paths.
   # Returns an empty array both for software that links against no libraries,
   # and for non-mach objects.
+  # @private
   def dynamically_linked_libraries
     mach_metadata.dylibs
   end
 
+  # @private
   def dylib_id
     mach_metadata.dylib_id
   end

Library/Homebrew/manpages/brew.1.md

@@ -92,7 +92,7 @@ Note that these flags should only appear after a command.
     and version, but if it fails, you'll have to make your own template. The wget
     formula serves as a simple example. For a complete cheat-sheet, have a look at
 
-    `$(brew --repository)/Library/Contributions/example-formula.rb`
+    <http://www.rubydoc.info/github/Homebrew/homebrew/master/frames>
 
     If `--autotools` is passed, create a basic template for an Autotools-style build.
     If `--cmake` is passed, create a basic template for a CMake-style build.

Library/Homebrew/utils.rb

@@ -80,6 +80,7 @@ def oh1(title)
   puts "#{Tty.green}==>#{Tty.white} #{title}#{Tty.reset}"
 end
 
+# Print a warning (do this rarely)
 def opoo(warning)
   $stderr.puts "#{Tty.yellow}Warning#{Tty.reset}: #{warning}"
 end

Library/Homebrew/utils/inreplace.rb

@@ -8,6 +8,13 @@ module Utils
   end
 
   module 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 var 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>
     def inreplace(paths, before = nil, after = nil)
       errors = {}
 

share/doc/homebrew/Formula-Cookbook.md

@@ -81,7 +81,7 @@ Formulae aren’t that complicated. [etl](https://github.com/Homebrew/homebrew/b
 
 And then [Git](https://github.com/Homebrew/homebrew/tree/master/Library/Formula/git.rb) and [flac](https://github.com/Homebrew/homebrew/tree/master/Library/Formula/flac.rb) show more advanced functionality.
 
-A more complete example-formula [cheat-sheet](https://github.com/Homebrew/homebrew/blob/master/Library/Contributions/example-formula.rb) shows almost all the stuff you can use in a Formula.
+Refer to the [Formula class API documentation](http://www.rubydoc.info/github/Homebrew/homebrew/master/frames) which shows all the stuff you can use in a Formula.
 
 ## Grab the URL
 

share/man/man1/brew.1

@@ -92,7 +92,7 @@ If \fB\-\-quiet\fR is passed, list only the names of commands without the header
 \fBcreate <URL> [\-\-autotools|\-\-cmake] [\-\-no\-fetch] [\-\-set\-name <name>] [\-\-set\-version <version>]\fR: Generate a formula for the downloadable file at \fIURL\fR and open it in the editor\. Homebrew will attempt to automatically derive the formula name and version, but if it fails, you\'ll have to make your own template\. The wget formula serves as a simple example\. For a complete cheat\-sheet, have a look at
 .
 .IP
-\fB$(brew \-\-repository)/Library/Contributions/example\-formula\.rb\fR
+\fIhttp://www\.rubydoc\.info/github/Homebrew/homebrew/master/frames\fR
 .
 .IP
 If \fB\-\-autotools\fR is passed, create a basic template for an Autotools\-style build\. If \fB\-\-cmake\fR is passed, create a basic template for a CMake\-style build\.