document formula path helpers

1 files changed, 10 insertions, 0 deletions

diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb
index e11aa0019..43a67079d 100644
--- a/Library/Homebrew/formula.rb
+++ b/Library/Homebrew/formula.rb
@@ -163,9 +163,13 @@ class Formula
     Keg.new(installed_prefix).version
   end
 
+  # The directory in the cellar that the formula is installed to.
+  # This directory contains the formula's name and version.
   def prefix(v=pkg_version)
     Pathname.new("#{HOMEBREW_CELLAR}/#{name}/#{v}")
   end
+  # The parent of the prefix; the named directory in the cellar containing all
+  # installed versions of this software
   def rack; prefix.parent end
 
   def bin;     prefix+'bin'     end
@@ -210,6 +214,12 @@ class Formula
   def plist_manual; self.class.plist_manual end
   def plist_startup; self.class.plist_startup end
 
+  # A stable path for this formula, when installed. Contains the formula name
+  # but no version number. Only the active version will be linked here if
+  # multiple versions are installed.
+  #
+  # This is the prefered way to refer a formula in plists or from another
+  # formula, as the path is stable even when the software is updated.
   def opt_prefix
     Pathname.new("#{HOMEBREW_PREFIX}/opt/#{name}")
   end