5 files changed, 28 insertions, 2 deletions
diff --git a/Library/Homebrew/extend/ARGV.rb b/Library/Homebrew/extend/ARGV.rb
index 706b62568..3e464bd06 100644
--- a/Library/Homebrew/extend/ARGV.rb
+++ b/Library/Homebrew/extend/ARGV.rb
@@ -200,7 +200,8 @@ module HomebrewArgvExtension
     value "env"
   end
 
-  # collect any supplied build flags into an array for reporting
+  # If the user passes any flags that trigger building over installing from
+  # a bottle, they are collected here and returned as an Array for checking.
   def collect_build_flags
     build_flags = []
 
diff --git a/Library/Homebrew/formula_installer.rb b/Library/Homebrew/formula_installer.rb
index 99d6c786a..7bed505b7 100644
--- a/Library/Homebrew/formula_installer.rb
+++ b/Library/Homebrew/formula_installer.rb
@@ -56,7 +56,9 @@ class FormulaInstaller
     @pour_failed   = false
   end
 
-  # called by install/reinstall/upgrade when no build tools are available
+  # When no build tools are available and build flags are passed through ARGV,
+  # it's necessary to interrupt the user before any sort of installation
+  # can proceed. Only invoked when the user has no developer tools.
   def self.prevent_build_flags
     build_flags = ARGV.collect_build_flags
 
@@ -232,6 +234,8 @@ class FormulaInstaller
     raise FormulaConflictError.new(formula, conflicts) unless conflicts.empty?
   end
 
+  # Compute and collect the dependencies needed by the formula currently
+  # being installed.
   def compute_dependencies
     req_map, req_deps = expand_requirements
     check_requirements(req_map)
@@ -240,6 +244,9 @@ class FormulaInstaller
     deps
   end
 
+  # Check that each dependency in deps has a bottle available, terminating
+  # abnormally with a BuildToolsError if one or more don't.
+  # Only invoked when the user has no developer tools.
   def check_dependencies_bottled(deps)
     unbottled = deps.select do |dep, _|
       formula = dep.to_formula
@@ -352,6 +359,10 @@ class FormulaInstaller
     @show_header = true unless deps.empty?
   end
 
+  # Installs the relocation tools (as provided by the cctools formula) as a hard
+  # dependency for every formula installed from a bottle when the user has no
+  # developer tools. Invoked unless the formula explicitly sets
+  # :any_skip_relocation in its bottle DSL.
   def install_relocation_tools
     cctools = CctoolsRequirement.new
     dependency = cctools.to_dependency
diff --git a/Library/Homebrew/os/mac.rb b/Library/Homebrew/os/mac.rb
index 814ef70a2..c2c909d76 100644
--- a/Library/Homebrew/os/mac.rb
+++ b/Library/Homebrew/os/mac.rb
@@ -36,6 +36,8 @@ module OS
       end
     end
 
+    # Locates a (working) copy of install_name_tool, guaranteed to function
+    # whether the user has developer tools installed or not.
     def install_name_tool
       if File.executable?(path = "#{HOMEBREW_PREFIX}/opt/cctools/bin/install_name_tool")
         Pathname.new(path)
@@ -44,6 +46,8 @@ module OS
       end
     end
 
+    # Locates a (working) copy of otool, guaranteed to function whether the user
+    # has developer tools installed or not.
     def otool
       if File.executable?(path = "#{HOMEBREW_PREFIX}/opt/cctools/bin/otool")
         Pathname.new(path)
@@ -52,6 +56,9 @@ module OS
       end
     end
 
+    # Checks if the user has any developer tools installed, either via Xcode
+    # or the CLT. Convenient for guarding against formula builds when building
+    # is impossible.
     def has_apple_developer_tools?
       Xcode.installed? || CLT.installed?
     end
diff --git a/Library/Homebrew/requirements/cctools_requirement.rb b/Library/Homebrew/requirements/cctools_requirement.rb
index 37be3207b..ab7f8cb59 100644
--- a/Library/Homebrew/requirements/cctools_requirement.rb
+++ b/Library/Homebrew/requirements/cctools_requirement.rb
@@ -1,3 +1,8 @@
+# Represents a general requirement for utilities normally installed by Xcode,
+# the CLT, or provided by the cctools formula. In particular, this requirement
+# allows Homebrew to pull in the cctools formula and use its utilities to
+# perform relocation operations on systems that do not have either Xcode or the
+# CLT installed (but still want to install bottled formulae).
 class CctoolsRequirement < Requirement
   fatal true
   default_formula 'cctools'
diff --git a/Library/Homebrew/software_spec.rb b/Library/Homebrew/software_spec.rb
index edc5f7645..e8148322e 100644
--- a/Library/Homebrew/software_spec.rb
+++ b/Library/Homebrew/software_spec.rb
@@ -245,6 +245,7 @@ class Bottle
     @spec.compatible_cellar?
   end
 
+  # Does the bottle need to be relocated?
   def skip_relocation?
     @spec.skip_relocation?
   end
@@ -288,6 +289,7 @@ class BottleSpecification
     cellar == :any || cellar == :any_skip_relocation || cellar == HOMEBREW_CELLAR.to_s
   end
 
+  # Does the Bottle this BottleSpecification belongs to need to be relocated?
   def skip_relocation?
     cellar == :any_skip_relocation
   end