Documented Gem::InstallerTestCase utility methods

lib/rubygems/installer_test_case.rb

@@ -61,11 +61,27 @@ class Gem::Installer
 
 ##
 # A test case for Gem::Installer.
-#--
-# TODO document these utility methods
 
 class Gem::InstallerTestCase < Gem::TestCase
 
+  ##
+  # Creates the following instance variables:
+  #
+  # @spec::
+  #   a spec named 'a', intended for regular installs
+  # @user_spec::
+  #   a spec named 'b', intended for user installs
+
+  # @gem::
+  #   the path to a built gem from @spec
+  # @user_spec::
+  #   the path to a built gem from @user_spec
+  #
+  # @installer::
+  #   a Gem::Installer for the @spec that installs into @gemhome
+  # @user_installer::
+  #   a Gem::Installer for the @user_spec that installs into Gem.user_dir
+
   def setup
     super
 
@@ -87,20 +103,29 @@ def setup
     @user_installer = util_installer @user_spec, Gem.user_dir, :user
   end
 
-  def util_gem_bindir spec = @spec
+  def util_gem_bindir spec = @spec # :nodoc:
     # TODO: deprecate
     spec.bin_dir
   end
 
-  def util_gem_dir spec = @spec
+  def util_gem_dir spec = @spec # :nodoc:
     # TODO: deprecate
     spec.gem_dir
   end
 
+  ##
+  # The path where installed executables live
+
   def util_inst_bindir
     File.join @gemhome, "bin"
   end
 
+  ##
+  # Adds an executable named "executable" to +spec+ with the given +shebang+.
+  #
+  # The executable is also written to the bin dir in @tmpdir and the installed
+  # gem directory for +spec+.
+
   def util_make_exec(spec = @spec, shebang = "#!/usr/bin/ruby")
     spec.executables = %w[executable]
     spec.files << 'bin/executable'
@@ -116,6 +141,14 @@ def util_make_exec(spec = @spec, shebang = "#!/usr/bin/ruby")
     end
   end
 
+  ##
+  # Builds the @spec gem and returns an installer for it.  The built gem
+  # includes:
+  #
+  #   bin/executable
+  #   lib/code.rb
+  #   ext/a/mkrf_conf.rb
+
   def util_setup_gem(ui = @ui) # HACK fix use_ui to make this automatic
     @spec.files << File.join('lib', 'code.rb')
     @spec.extensions << File.join('ext', 'a', 'mkrf_conf.rb')
@@ -142,9 +175,15 @@ def util_setup_gem(ui = @ui) # HACK fix use_ui to make this automatic
     @installer = Gem::Installer.new @gem
   end
 
+  ##
+  # Creates an installer for +spec+ that will install into +gem_home+.  If
+  # +user+ is true a user-install will be performed.
+
   def util_installer(spec, gem_home, user=false)
     Gem::Installer.new(spec.cache_file,
                        :install_dir => gem_home,
                        :user_install => user)
   end
+
 end
+