* 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

1 files changed, 154 insertions, 26 deletions

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