* lib/rubygems: Update RubyGems to master 0886307. This commit

  improves documentation and should bring ruby above 75% documented on
  rubyci.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@43369 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

12 files changed, 300 insertions, 54 deletions

diff --git a/lib/rubygems/core_ext/kernel_gem.rb b/lib/rubygems/core_ext/kernel_gem.rb
index f946d0d5d7..3405233ab1 100644
--- a/lib/rubygems/core_ext/kernel_gem.rb
+++ b/lib/rubygems/core_ext/kernel_gem.rb
@@ -1,3 +1,9 @@
+##
+# RubyGems adds the #gem method to allow activation of specific gem versions
+# and overrides the #require method on Kernel to make gems appear as if they
+# live on the <code>$LOAD_PATH</code>.  See the documentation of these methods
+# for further detail.
+
 module Kernel
 
   # REFACTOR: This should be pulled out into some kind of hacks file.
diff --git a/lib/rubygems/exceptions.rb b/lib/rubygems/exceptions.rb
index 9aef89956e..30d9880d8a 100644
--- a/lib/rubygems/exceptions.rb
+++ b/lib/rubygems/exceptions.rb
@@ -81,7 +81,16 @@ end
 
 class Gem::GemNotFoundException < Gem::Exception; end
 
+##
+# Raised by the DependencyInstaller when a specific gem cannot be found
+
 class Gem::SpecificGemNotFoundException < Gem::GemNotFoundException
+
+  ##
+  # Creates a new SpecificGemNotFoundException for a gem with the given +name+
+  # and +version+.  Any +errors+ encountered when attempting to find the gem
+  # are also stored.
+
   def initialize(name, version, errors=nil)
     super "Could not find a valid gem '#{name}' (#{version}) locally or in a repository"
 
@@ -90,7 +99,21 @@ class Gem::SpecificGemNotFoundException < Gem::GemNotFoundException
     @errors = errors
   end
 
-  attr_reader :name, :version, :errors
+  ##
+  # The name of the gem that could not be found.
+
+  attr_reader :name
+
+  ##
+  # The version of the gem that could not be found.
+
+  attr_reader :version
+
+  ##
+  # Errors encountered attempting to find the gem.
+
+  attr_reader :errors
+
 end
 
 ##
@@ -160,6 +183,9 @@ class Gem::RemoteSourceException < Gem::Exception; end
 
 class Gem::RubyVersionMismatch < Gem::Exception; end
 
+##
+# Raised by Gem::Validator when something is not right in a gem.
+
 class Gem::VerificationError < Gem::Exception; end
 
 ##
@@ -167,8 +193,15 @@ class Gem::VerificationError < Gem::Exception; end
 # exit_code
 
 class Gem::SystemExitException < SystemExit
+
+  ##
+  # The exit code for the process
+
   attr_accessor :exit_code
 
+  ##
+  # Creates a new SystemExitException with the given +exit_code+
+
   def initialize(exit_code)
     @exit_code = exit_code
 
@@ -183,8 +216,16 @@ end
 
 class Gem::UnsatisfiableDependencyError < Gem::Exception
 
+  ##
+  # The unsatisfiable dependency.  This is a
+  # Gem::DependencyResolver::DependencyRequest, not a Gem::Dependency
+
   attr_reader :dependency
 
+  ##
+  # Creates a new UnsatisfiableDepedencyError for the unsatisfiable
+  # Gem::DependencyResolver::DependencyRequest +dep+
+
   def initialize dep
     requester = dep.requester ? dep.requester.request : '(unknown)'
 
diff --git a/lib/rubygems/psych_additions.rb b/lib/rubygems/psych_additions.rb
index dcc13fdf2e..0e4ebbd50c 100644
--- a/lib/rubygems/psych_additions.rb
+++ b/lib/rubygems/psych_additions.rb
@@ -4,6 +4,6 @@
 # blows up.
 
 module Psych # :nodoc:
-  class PrivateType
+  class PrivateType # :nodoc:
   end
 end
diff --git a/lib/rubygems/specification.rb b/lib/rubygems/specification.rb
index b2c2acc294..1aed2cebed 100644
--- a/lib/rubygems/specification.rb
+++ b/lib/rubygems/specification.rb
@@ -71,13 +71,13 @@ class Gem::Specification < Gem::BasicSpecification
   #
   # NOTE RubyGems < 1.2 cannot load specification versions > 2.
 
-  CURRENT_SPECIFICATION_VERSION = 4
+  CURRENT_SPECIFICATION_VERSION = 4 # :nodoc:
 
   ##
   # An informal list of changes to the specification.  The highest-valued
   # key should be equal to the CURRENT_SPECIFICATION_VERSION.
 
-  SPECIFICATION_VERSION_HISTORY = {
+  SPECIFICATION_VERSION_HISTORY = { # :nodoc:
     -1 => ['(RubyGems versions up to and including 0.7 did not have versioned specifications)'],
     1  => [
       'Deprecated "test_suite_file" in favor of the new, but equivalent, "test_files"',
@@ -95,12 +95,18 @@ class Gem::Specification < Gem::BasicSpecification
     ]
   }
 
-  MARSHAL_FIELDS = { -1 => 16, 1 => 16, 2 => 16, 3 => 17, 4 => 18 }
+  MARSHAL_FIELDS = { # :nodoc:
+    -1 => 16,
+     1 => 16,
+     2 => 16,
+     3 => 17,
+     4 => 18,
+  }
 
   today = Time.now.utc
-  TODAY = Time.utc(today.year, today.month, today.day)
+  TODAY = Time.utc(today.year, today.month, today.day) # :nodoc:
 
-  LOAD_CACHE = {}
+  LOAD_CACHE = {} # :nodoc:
 
   private_constant :LOAD_CACHE if defined? private_constant
 
@@ -153,7 +159,7 @@ class Gem::Specification < Gem::BasicSpecification
     :version                   => nil,
   }
 
-  Dupable = { }
+  Dupable = { } # :nodoc:
 
   @@default_value.each do |k,v|
     case v
@@ -1486,10 +1492,11 @@ class Gem::Specification < Gem::BasicSpecification
     @date ||= TODAY
   end
 
-  DateTimeFormat = /\A
-                     (\d{4})-(\d{2})-(\d{2})
-                     (\s+ \d{2}:\d{2}:\d{2}\.\d+ \s* (Z | [-+]\d\d:\d\d) )?
-                   \Z/x
+  DateTimeFormat = # :nodoc:
+    /\A
+     (\d{4})-(\d{2})-(\d{2})
+     (\s+ \d{2}:\d{2}:\d{2}\.\d+ \s* (Z | [-+]\d\d:\d\d) )?
+     \Z/x
 
   ##
   # The date this gem was created
@@ -1850,7 +1857,7 @@ class Gem::Specification < Gem::BasicSpecification
 
   private :invalidate_memoized_attributes
 
-  def inspect
+  def inspect # :nodoc:
     if $DEBUG
       super
     else
diff --git a/lib/rubygems/syck_hack.rb b/lib/rubygems/syck_hack.rb
index 5356aa081e..1229fe7c7a 100644
--- a/lib/rubygems/syck_hack.rb
+++ b/lib/rubygems/syck_hack.rb
@@ -10,7 +10,7 @@
 # class no matter if the full yaml library has loaded or not.
 #
 
-module YAML
+module YAML # :nodoc:
   # In newer 1.9.2, there is a Syck toplevel constant instead of it
   # being underneith YAML. If so, reference it back under YAML as
   # well.
@@ -29,7 +29,7 @@ module YAML
   # loaded, so lets define a stub for DefaultKey.
   elsif !defined? YAML::Syck
     module Syck
-      class DefaultKey
+      class DefaultKey # :nodoc:
       end
     end
   end
diff --git a/lib/rubygems/test_case.rb b/lib/rubygems/test_case.rb
index 1e6d9feeeb..19d3cfd134 100644
--- a/lib/rubygems/test_case.rb
+++ b/lib/rubygems/test_case.rb
@@ -1117,25 +1117,46 @@ Also, a list:
     return name, vendor_spec.version, directory
   end
 
+  ##
+  # The StaticSet is a static set of gem specifications used for testing only.
+  # It is available by requiring Gem::TestCase.
+
   class StaticSet
+
+    ##
+    # Creates a new StaticSet for the given +specs+
+
     def initialize(specs)
       @specs = specs
     end
 
+    ##
+    # Adds +spec+ to this set.
+
     def add spec
       @specs << spec
     end
 
+    ##
+    # Finds +dep+ in this set.
+
     def find_spec(dep)
       @specs.reverse_each do |s|
         return s if dep.matches_spec? s
       end
     end
 
+    ##
+    # Finds all gems matching +dep+ in this set.
+
     def find_all(dep)
       @specs.find_all { |s| dep.matches_spec? s }
     end
 
+    ##
+    # Loads a Gem::Specification from this set which has the given +name+,
+    # version +ver+, +platform+.  The +source+ is ignored.
+
     def load_spec name, ver, platform, source
       dep = Gem::Dependency.new name, ver
       spec = find_spec dep
@@ -1145,7 +1166,7 @@ Also, a list:
       end
     end
 
-    def prefetch(reqs)
+    def prefetch reqs # :nodoc:
     end
   end
 
diff --git a/lib/rubygems/test_utilities.rb b/lib/rubygems/test_utilities.rb
index eed42f59a7..eddabeb6fd 100644
--- a/lib/rubygems/test_utilities.rb
+++ b/lib/rubygems/test_utilities.rb
@@ -168,6 +168,10 @@ end
 # This class was added to flush out problems in Rubinius' IO implementation.
 
 class TempIO < Tempfile
+
+  ##
+  # Creates a new TempIO that will be initialized to contain +string+.
+
   def initialize(string = '')
     super "TempIO"
     binmode
@@ -175,6 +179,9 @@ class TempIO < Tempfile
     rewind
   end
 
+  ##
+  # The content of the TempIO as a String.
+
   def string
     flush
     Gem.read_binary path
diff --git a/lib/rubygems/uninstaller.rb b/lib/rubygems/uninstaller.rb
index eb150497ca..a1caacb10d 100644
--- a/lib/rubygems/uninstaller.rb
+++ b/lib/rubygems/uninstaller.rb
@@ -281,18 +281,30 @@ class Gem::Uninstaller
     full_path == spec.full_gem_path || original_path == spec.full_gem_path
   end
 
-  def dependencies_ok?(spec)
+  ##
+  # Returns true if it is OK to remove +spec+ or this is a forced
+  # uninstallation.
+
+  def dependencies_ok? spec # :nodoc:
     return true if @force_ignore
 
     deplist = Gem::DependencyList.from_specs
     deplist.ok_to_remove?(spec.full_name, @check_dev)
   end
 
-  def abort_on_dependent?
+  ##
+  # Should the uninstallation abort if a dependency will go unsatisfied?
+  #
+  # See ::new.
+
+  def abort_on_dependent? # :nodoc:
     @abort_on_dependent
   end
 
-  def ask_if_ok(spec)
+  ##
+  # Asks if it is OK to remove +spec+.  Returns true if it is OK.
+
+  def ask_if_ok spec # :nodoc:
     msg = ['']
     msg << 'You have requested to uninstall the gem:'
     msg << "\t#{spec.full_name}"
@@ -313,7 +325,10 @@ class Gem::Uninstaller
     return ask_yes_no(msg.join("\n"), false)
   end
 
-  def formatted_program_filename(filename)
+  ##
+  # Returns the formatted version of the executable +filename+
+
+  def formatted_program_filename filename # :nodoc:
     # TODO perhaps the installer should leave a small manifest
     # of what it did for us to find rather than trying to recreate
     # it again.
diff --git a/lib/rubygems/uri_formatter.rb b/lib/rubygems/uri_formatter.rb
index 935d9b52ed..68aacc6369 100644
--- a/lib/rubygems/uri_formatter.rb
+++ b/lib/rubygems/uri_formatter.rb
@@ -1,13 +1,30 @@
 require 'cgi'
 require 'uri'
 
+##
+# The UriFormatter handles URIs from user-input and escaping.
+#
+#   uf = Gem::UriFormatter.new 'example.com'
+#
+#   p uf.normalize #=> 'http://example.com'
+
 class Gem::UriFormatter
+
+  ##
+  # The URI to be formatted.
+
   attr_reader :uri
 
+  ##
+  # Creates a new URI formatter for +uri+.
+
   def initialize uri
     @uri = uri
   end
 
+  ##
+  # Escapes the #uri for use as a CGI parameter
+
   def escape
     return unless @uri
     CGI.escape @uri
@@ -20,6 +37,9 @@ class Gem::UriFormatter
     (@uri =~ /^(https?|ftp|file):/i) ? @uri : "http://#{@uri}"
   end
 
+  ##
+  # Unescapes the #uri which came from a CGI parameter
+
   def unescape
     return unless @uri
     CGI.unescape @uri
diff --git a/lib/rubygems/user_interaction.rb b/lib/rubygems/user_interaction.rb
index 0974476507..0e4449a2ec 100644
--- a/lib/rubygems/user_interaction.rb
+++ b/lib/rubygems/user_interaction.rb
@@ -66,9 +66,13 @@ module Gem::DefaultUserInteraction
 end
 
 ##
-# Make the default UI accessible without the "ui." prefix.  Classes
-# including this module may use the interaction methods on the default UI
-# directly.  Classes may also reference the ui and ui= methods.
+# UserInteraction allows RubyGems to interact with the user through standard
+# methods that can be replaced with more-specific UI methods for different
+# displays.
+#
+# Since UserInteraction dispatches to a concrete UI class you may need to
+# reference other classes for specific behavior such as Gem::ConsoleUI or
+# Gem::SilentUI.
 #
 # Example:
 #
@@ -84,40 +88,69 @@ module Gem::UserInteraction
 
   include Gem::DefaultUserInteraction
 
-  def alert(*args)
-    ui.alert(*args)
+  ##
+  # Displays an alert +statement+.  Asks a +question+ if given.
+
+  def alert statement, question = nil
+    ui.alert statement, question
   end
 
-  def alert_error(*args)
-    ui.alert_error(*args)
+  ##
+  # Displays an error +statement+ to the error output location.  Asks a
+  # +question+ if given.
+
+  def alert_error statement, question = nil
+    ui.alert_error statement, question
   end
 
-  def alert_warning(*args)
-    ui.alert_warning(*args)
+  ##
+  # Displays a warning +statement+ to the warning output location.  Asks a
+  # +question+ if given.
+
+  def alert_warning statement, question = nil
+    ui.alert_warning statement, question
   end
 
-  def ask(*args)
-    ui.ask(*args)
+  ##
+  # Asks a +question+ and returns the answer.
+
+  def ask question
+    ui.ask question
   end
 
-  def ask_for_password(*args)
-    ui.ask_for_password(*args)
+  ##
+  # Asks for a password with a +prompt+
+
+  def ask_for_password prompt
+    ui.ask_for_password prompt
   end
 
-  def ask_yes_no(*args)
-    ui.ask_yes_no(*args)
+  ##
+  # Asks a yes or no +question+.  Returns true for yes, false for no.
+
+  def ask_yes_no question, default = nil
+    ui.ask_yes_no question, default
   end
 
-  def choose_from_list(*args)
-    ui.choose_from_list(*args)
+  ##
+  # Asks the user to answer +question+ with an answer from the given +list+.
+
+  def choose_from_list question, list
+    ui.choose_from_list question, list
   end
 
-  def say(*args)
-    ui.say(*args)
+  ##
+  # Displays the given +statement+ on the standard output (or equivalent).
+
+  def say statement = ''
+    ui.say statement
   end
 
-  def terminate_interaction(*args)
-    ui.terminate_interaction(*args)
+  ##
+  # Terminates the RubyGems process with the given +exit_code+
+
+  def terminate_interaction exit_code = 0
+    ui.terminate_interaction exit_code
   end
 end
 
@@ -126,7 +159,26 @@ end
 
 class Gem::StreamUI
 
-  attr_reader :ins, :outs, :errs
+  ##
+  # The input stream
+
+  attr_reader :ins
+
+  ##
+  # The output stream
+
+  attr_reader :outs
+
+  ##
+  # The error stream
+
+  attr_reader :errs
+
+  ##
+  # Creates a new StreamUI wrapping +in_stream+ for user input, +out_stream+
+  # for standard output, +err_stream+ for error output.  If +usetty+ is true
+  # then special operations (like asking for passwords) will use the TTY
+  # commands to disable character echo.
 
   def initialize(in_stream, out_stream, err_stream=STDERR, usetty=true)
     @ins = in_stream
@@ -135,6 +187,9 @@ class Gem::StreamUI
     @usetty = usetty
   end
 
+  ##
+  # Returns true if TTY methods should be used on this StreamUI.
+
   def tty?
     if RUBY_VERSION < '1.9.3' and RUBY_PLATFORM =~ /mingw|mswin/ then
       @usetty
@@ -310,8 +365,7 @@ class Gem::StreamUI
   end
 
   ##
-  # Display a warning in a location expected to get error messages.  Will
-  # ask +question+ if it is not nil.
+  # Display a warning on stderr.  Will ask +question+ if it is not nil.
 
   def alert_warning(statement, question=nil)
     @errs.puts "WARNING:  #{statement}"
@@ -364,14 +418,29 @@ class Gem::StreamUI
   # An absolutely silent progress reporter.
 
   class SilentProgressReporter
+
+    ##
+    # The count of items is never updated for the silent progress reporter.
+
     attr_reader :count
 
+    ##
+    # Creates a silent progress reporter that ignores all input arguments.
+
     def initialize(out_stream, size, initial_message, terminal_message = nil)
     end
 
+    ##
+    # Does not print +message+ when updated as this object has taken a vow of
+    # silence.
+
     def updated(message)
     end
 
+    ##
+    # Does not print anything when complete as this object has taken a vow of
+    # silence.
+
     def done
     end
   end
@@ -383,8 +452,16 @@ class Gem::StreamUI
 
     include Gem::DefaultUserInteraction
 
+    ##
+    # The number of progress items counted so far.
+
     attr_reader :count
 
+    ##
+    # Creates a new progress reporter that will write to +out_stream+ for
+    # +size+ items.  Shows the given +initial_message+ when progress starts
+    # and the +terminal_message+ when it is complete.
+
     def initialize(out_stream, size, initial_message,
                    terminal_message = "complete")
       @out = out_stream
@@ -420,8 +497,16 @@ class Gem::StreamUI
 
     include Gem::DefaultUserInteraction
 
+    ##
+    # The number of progress items counted so far.
+
     attr_reader :count
 
+    ##
+    # Creates a new progress reporter that will write to +out_stream+ for
+    # +size+ items.  Shows the given +initial_message+ when progress starts
+    # and the +terminal_message+ when it is complete.
+
     def initialize(out_stream, size, initial_message,
                    terminal_message = 'complete')
       @out = out_stream
@@ -468,15 +553,30 @@ class Gem::StreamUI
   # An absolutely silent download reporter.
 
   class SilentDownloadReporter
+
+    ##
+    # The silent download reporter ignores all arguments
+
     def initialize(out_stream, *args)
     end
 
+    ##
+    # The silent download reporter does not display +filename+ or care about
+    # +filesize+ because it is silent.
+
     def fetch(filename, filesize)
     end
 
+    ##
+    # Nothing can update the silent download reporter.
+
     def update(current)
     end
 
+    ##
+    # The silent download reporter won't tell you when the download is done.
+    # Because it is silent.
+
     def done
     end
   end
@@ -485,13 +585,35 @@ class Gem::StreamUI
   # A progress reporter that prints out messages about the current progress.
 
   class VerboseDownloadReporter
-    attr_reader :file_name, :total_bytes, :progress
+
+    ##
+    # The current file name being displayed
+
+    attr_reader :file_name
+
+    ##
+    # The total bytes in the file
+
+    attr_reader :total_bytes
+
+    ##
+    # The current progress (0 to 100)
+
+    attr_reader :progress
+
+    ##
+    # Creates a new verbose download reporter that will display on
+    # +out_stream+.  The other arguments are ignored.
 
     def initialize(out_stream, *args)
       @out = out_stream
       @progress = 0
     end
 
+    ##
+    # Tells the download reporter that the +file_name+ is being fetched and
+    # contains +total_bytes+.
+
     def fetch(file_name, total_bytes)
       @file_name = file_name
       @total_bytes = total_bytes.to_i
@@ -500,6 +622,9 @@ class Gem::StreamUI
       update_display(false)
     end
 
+    ##
+    # Updates the verbose download reporter for the given number of +bytes+.
+
     def update(bytes)
       new_progress = if @units == 'B' then
                        bytes
@@ -513,6 +638,9 @@ class Gem::StreamUI
       update_display
     end
 
+    ##
+    # Indicates the download is complete.
+
     def done
       @progress = 100 if @units == '%'
       update_display(true, true)
@@ -520,7 +648,7 @@ class Gem::StreamUI
 
     private
 
-    def update_display(show_progress = true, new_line = false)
+    def update_display(show_progress = true, new_line = false) # :nodoc:
       return unless @out.tty?
 
       if show_progress then
diff --git a/lib/rubygems/validator.rb b/lib/rubygems/validator.rb
index e5183d401f..1436a93ae6 100644
--- a/lib/rubygems/validator.rb
+++ b/lib/rubygems/validator.rb
@@ -14,7 +14,7 @@ class Gem::Validator
 
   include Gem::UserInteraction
 
-  def initialize
+  def initialize # :nodoc:
     require 'find'
   end
 
@@ -57,8 +57,11 @@ class Gem::Validator
 
   public
 
+  ##
+  # Describes a problem with a file in a gem.
+
   ErrorData = Struct.new :path, :problem do
-    def <=> other
+    def <=> other # :nodoc:
       return nil unless self.class === other
 
       [path, problem] <=> [other.path, other.problem]
diff --git a/lib/rubygems/version.rb b/lib/rubygems/version.rb
index 10b0503294..15e72292b1 100644
--- a/lib/rubygems/version.rb
+++ b/lib/rubygems/version.rb
@@ -174,8 +174,6 @@ class Gem::Version
   #   ver2 = Version.create(ver1)       # -> (ver1)
   #   ver3 = Version.create(nil)        # -> nil
 
-  # REFACTOR: There's no real reason this should be separate from #initialize.
-
   def self.create input
     if self === input then # check yourself before you wreck yourself
       input
@@ -188,7 +186,7 @@ class Gem::Version
 
   @@all = {}
 
-  def self.new version
+  def self.new version # :nodoc:
     @@all[version] ||= super
   end
 
@@ -255,17 +253,17 @@ class Gem::Version
     initialize array[0]
   end
 
-  def yaml_initialize(tag, map)
+  def yaml_initialize(tag, map) # :nodoc:
     @version = map['version']
     @segments = nil
     @hash = nil
   end
 
-  def to_yaml_properties
+  def to_yaml_properties # :nodoc:
     ["@version"]
   end
 
-  def encode_with coder
+  def encode_with coder # :nodoc:
     coder.add 'version', @version
   end