More API documentation.

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

Closes 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

@@ -1,4 +1,8 @@
-# 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

@@ -1,13 +1,28 @@
 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 @@ def with?(val)
     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 @@ def generate!
 
   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 @@
 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 @@ def man
     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

@@ -1,3 +1,4 @@
+# @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

@@ -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 @@ def append_path(key, path)
     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 @@ def fcflags
     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 @@ def compiler
     end
   end
 
+  # @private
   def determine_cc
     COMPILER_SYMBOL_MAP.invert.fetch(compiler, compiler)
   end
@@ -159,13 +181,14 @@ def determine_cc
     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 @@ def fortran
   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 @@ def gcc_version_formula(name)
     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 "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 @@ def self.extended(base)
     end
   end
 
+  # @private
   def setup_build_environment(formula = nil)
     super
 
@@ -69,6 +72,7 @@ def setup_build_environment(formula = nil)
     end
   end
 
+  # @private
   def determine_pkg_config_libdir
     paths = []
     paths << "#{HOMEBREW_PREFIX}/lib/pkgconfig"
@@ -106,11 +110,13 @@ def deparallelize
     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 @@ def libstdcxx
     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 @@ def set_cflags(val)
 
   # 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 @@ def set_cpu_flags(flags, default = DEFAULT_FLAGS, map = Hardware::CPU.optimizati
     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 @@ def effective_arch
     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 @@ def make_jobs
   end
 
   # This method does nothing in stdenv since there's no arg refurbishment
+  # @private
   def refurbish_args; end
 end