Document Formula attributes.

The beginnings of some decent API documentation.

Also, tweak `.yardopts` to better fix our internal style.

3 files changed, 103 insertions, 14 deletions

diff --git a/.yardopts b/.yardopts
index 821b67c36..e519cd9e6 100644
--- a/.yardopts
+++ b/.yardopts
@@ -1,6 +1,8 @@
 --title "Homebrew"
 --main Library/Homebrew/README.md
---exclude Library/Homebrew/test/vendor/
+--markup markdown
+--no-private
+--exclude Library/Homebrew/test/
 --exclude Library/Homebrew/vendor/
 Library/Homebrew/**/*.rb
 -
diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb
index c1f3d3ff1..49320a673 100644
--- a/Library/Homebrew/formula.rb
+++ b/Library/Homebrew/formula.rb
@@ -10,20 +10,76 @@ require 'software_spec'
 require 'install_renamed'
 require 'pkg_version'
 
+# A formula provides instructions and metadata for Homebrew to install a piece
+# of software. Every Homebrew formula is a {Formula}.
+# All subclasses of {Formula} (and all Ruby classes) have to be named
+# `UpperCase` and `not-use-dashes`.
+# A formula specified in `this-formula.rb` should have a class named
+# `ThisFormula`. Homebrew does enforce that the name of the file and the class
+# correspond.
+# Make sure you check with `brew search` that the name is free!
+# @abstract
 class Formula
   include FileUtils
   include Utils::Inreplace
   extend Enumerable
 
-  attr_reader :name, :path
-  attr_reader :stable, :devel, :head, :active_spec
-  attr_reader :pkg_version, :revision
-
-  # The current working directory during builds and tests.
-  # Will only be non-nil inside #stage and #test.
-  attr_reader :buildpath, :testpath
-
+  # The name of this {Formula}.
+  # e.g. `this-formula`
+  attr_reader :name
+
+  # The full path to this {Formula}.
+  # e.g. `/usr/local/Library/Formula/this-formula.rb`
+  attr_reader :path
+
+  # The stable (and default) {SoftwareSpec} for this {Formula}
+  # This contains all the attributes like e.g. {#url}, {.sha1} that apply to
+  # the stable version of this formula.
+  attr_reader :stable
+
+  # The development {SoftwareSpec} for this {Formula}.
+  # Installed when using `brew install --devel`
+  # `nil` if there is no development version.
+  # @see #stable
+  attr_reader :devel
+
+  # The HEAD {SoftwareSpec} for this {Formula}.
+  # Installed when using `brew install --HEAD`
+  # This is always installed with the version `HEAD` and taken from the latest
+  # commit in the version control system.
+  # `nil` if there is no HEAD version.
+  # @see #stable
+  attr_reader :head
+
+  # The currently active SoftwareSpec.
+  # Defaults to stable unless `--devel` or `--HEAD` is passed.
+  # @private
+  attr_reader :active_spec
+
+  # The {PkgVersion} for this formula with version and {#revision} information.
+  attr_reader :pkg_version
+
+  # Used for creating new Homebrew versions of software without new upstream
+  # versions.
+  # @see .revision
+  attr_reader :revision
+
+  # The current working directory during builds.
+  # Will only be non-`nil` inside {#install}.
+  attr_reader :buildpath
+
+  # The current working directory during tests.
+  # Will only be non-`nil` inside {#test}.
+  attr_reader :testpath
+
+  # When installing a bottle (binary package) from a local path this will be
+  # set to the full path to the bottle tarball. If not, it will be `nil`.
   attr_accessor :local_bottle_path
+
+  # The {BuildOptions} for this {Formula}. Lists the arguments passed and any
+  # {#options} in the {Formula}. Note that these may differ at different times
+  # during the installation of a {Formula}. This is annoying but the result of
+  # state that we're trying to eliminate.
   attr_accessor :build
 
   def initialize(name, path, spec)
@@ -233,8 +289,10 @@ class Formula
   # tell the user about any caveats regarding this package, return a string
   def caveats; nil end
 
-  # Deprecated
+  # @deprecated
   DATA = :DATA
+
+  # @deprecated
   def patches; {} end
 
   # rarely, you don't want your library symlinked into the main prefix
@@ -267,6 +325,7 @@ class Formula
   end
 
   # yields self with current working directory set to the uncompressed tarball
+  # @private
   def brew
     validate_attributes :name, :version
 
@@ -347,7 +406,7 @@ class Formula
     ]
   end
 
-  # Deprecated
+  # @deprecated
   def python(options={}, &block)
     opoo 'Formula#python is deprecated and will go away shortly.'
     block.call if block_given?
@@ -648,8 +707,32 @@ class Formula
   class << self
     include BuildEnvironmentDSL
 
+    # The reason for why this software is not linked (by default) to
+    # {::HOMEBREW_PREFIX}.
     attr_reader :keg_only_reason
-    attr_rw :homepage, :plist_startup, :plist_manual, :revision
+
+    # @!attribute [rw]
+    # The homepage for the software. Used by users to get more information
+    # about the software and Homebrew maintainers as a point of contact for
+    # e.g. submitting patches.
+    # Can be opened by running `brew home example-formula`.
+    attr_rw :homepage
+
+    # @!attribute [rw]
+    # The `:startup` attribute set by {.plist_options}.
+    attr_rw :plist_startup
+
+    # @!attribute [rw]
+    # The `:manual` attribute set by {.plist_options}.
+    attr_rw :plist_manual
+
+    # @!attribute [rw]
+    # Used for creating new Homebrew versions of software without new upstream
+    # versions. For example, if we bump the major version of a library this
+    # {Formula} {.depends_on} then we may need to update the `revision` of this
+    # {Formula} to install a new version linked against the new library version.
+    # `0` if unset.
+    attr_rw :revision
 
     def specs
       @specs ||= [stable, devel, head].freeze
diff --git a/Library/Homebrew/global.rb b/Library/Homebrew/global.rb
index 00f076c86..556276546 100644
--- a/Library/Homebrew/global.rb
+++ b/Library/Homebrew/global.rb
@@ -48,8 +48,12 @@ if not defined? HOMEBREW_BREW_FILE
   HOMEBREW_BREW_FILE = ENV['HOMEBREW_BREW_FILE'] || which('brew').to_s
 end
 
-HOMEBREW_PREFIX = Pathname.new(HOMEBREW_BREW_FILE).dirname.parent # Where we link under
-HOMEBREW_REPOSITORY = Pathname.new(HOMEBREW_BREW_FILE).realpath.dirname.parent # Where .git is found
+# Where we link under
+HOMEBREW_PREFIX = Pathname.new(HOMEBREW_BREW_FILE).dirname.parent
+
+# Where .git is found
+HOMEBREW_REPOSITORY = Pathname.new(HOMEBREW_BREW_FILE).realpath.dirname.parent
+
 HOMEBREW_LIBRARY = HOMEBREW_REPOSITORY/"Library"
 HOMEBREW_CONTRIB = HOMEBREW_REPOSITORY/"Library/Contributions"