[前][次][番号順一覧][スレッド一覧]

ruby-changes:31290

From: drbrain <ko1@a...>
Date: Sun, 20 Oct 2013 10:33:26 +0900 (JST)
Subject: [ruby-changes:31290] drbrain:r43369 (trunk): * lib/rubygems: Update RubyGems to master 0886307. This commit

drbrain	2013-10-20 10:33:19 +0900 (Sun, 20 Oct 2013)

  New Revision: 43369

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=43369

  Log:
    * lib/rubygems:  Update RubyGems to master 0886307.  This commit
      improves documentation and should bring ruby above 75% documented on
      rubyci.

  Modified files:
    trunk/ChangeLog
    trunk/lib/rubygems/core_ext/kernel_gem.rb
    trunk/lib/rubygems/exceptions.rb
    trunk/lib/rubygems/psych_additions.rb
    trunk/lib/rubygems/specification.rb
    trunk/lib/rubygems/syck_hack.rb
    trunk/lib/rubygems/test_case.rb
    trunk/lib/rubygems/test_utilities.rb
    trunk/lib/rubygems/uninstaller.rb
    trunk/lib/rubygems/uri_formatter.rb
    trunk/lib/rubygems/user_interaction.rb
    trunk/lib/rubygems/validator.rb
    trunk/lib/rubygems/version.rb
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 43368)
+++ ChangeLog	(revision 43369)
@@ -1,3 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Sun Oct 20 10:32:48 2013  Eric Hodel  <drbrain@s...>
+
+	* lib/rubygems:  Update RubyGems to master 0886307.  This commit
+	  improves documentation and should bring ruby above 75% documented on
+	  rubyci.
+
 Sun Oct 20 09:30:56 2013  Eric Hodel  <drbrain@s...>
 
 	* lib/rubygems:  Update to RubyGems master 3de7e0f.  Changes:
Index: lib/rubygems/validator.rb
===================================================================
--- lib/rubygems/validator.rb	(revision 43368)
+++ lib/rubygems/validator.rb	(revision 43369)
@@ -14,7 +14,7 @@ class Gem::Validator https://github.com/ruby/ruby/blob/trunk/lib/rubygems/validator.rb#L14
 
   include Gem::UserInteraction
 
-  def initialize
+  def initialize # :nodoc:
     require 'find'
   end
 
@@ -57,8 +57,11 @@ class Gem::Validator https://github.com/ruby/ruby/blob/trunk/lib/rubygems/validator.rb#L57
 
   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]
Index: lib/rubygems/syck_hack.rb
===================================================================
--- lib/rubygems/syck_hack.rb	(revision 43368)
+++ lib/rubygems/syck_hack.rb	(revision 43369)
@@ -10,7 +10,7 @@ https://github.com/ruby/ruby/blob/trunk/lib/rubygems/syck_hack.rb#L10
 # 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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/syck_hack.rb#L29
   # loaded, so lets define a stub for DefaultKey.
   elsif !defined? YAML::Syck
     module Syck
-      class DefaultKey
+      class DefaultKey # :nodoc:
       end
     end
   end
Index: lib/rubygems/specification.rb
===================================================================
--- lib/rubygems/specification.rb	(revision 43368)
+++ lib/rubygems/specification.rb	(revision 43369)
@@ -71,13 +71,13 @@ class Gem::Specification < Gem::BasicSpe https://github.com/ruby/ruby/blob/trunk/lib/rubygems/specification.rb#L71
   #
   # 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::BasicSpe https://github.com/ruby/ruby/blob/trunk/lib/rubygems/specification.rb#L95
     ]
   }
 
-  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::BasicSpe https://github.com/ruby/ruby/blob/trunk/lib/rubygems/specification.rb#L159
     :version                   => nil,
   }
 
-  Dupable = { }
+  Dupable = { } # :nodoc:
 
   @@default_value.each do |k,v|
     case v
@@ -1486,10 +1492,11 @@ class Gem::Specification < Gem::BasicSpe https://github.com/ruby/ruby/blob/trunk/lib/rubygems/specification.rb#L1492
     @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::BasicSpe https://github.com/ruby/ruby/blob/trunk/lib/rubygems/specification.rb#L1857
 
   private :invalidate_memoized_attributes
 
-  def inspect
+  def inspect # :nodoc:
     if $DEBUG
       super
     else
Index: lib/rubygems/exceptions.rb
===================================================================
--- lib/rubygems/exceptions.rb	(revision 43368)
+++ lib/rubygems/exceptions.rb	(revision 43369)
@@ -81,7 +81,16 @@ end https://github.com/ruby/ruby/blob/trunk/lib/rubygems/exceptions.rb#L81
 
 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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/exceptions.rb#L99
     @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:: https://github.com/ruby/ruby/blob/trunk/lib/rubygems/exceptions.rb#L183
 
 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::Exce https://github.com/ruby/ruby/blob/trunk/lib/rubygems/exceptions.rb#L193
 # 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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/exceptions.rb#L216
 
 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)'
 
Index: lib/rubygems/uri_formatter.rb
===================================================================
--- lib/rubygems/uri_formatter.rb	(revision 43368)
+++ lib/rubygems/uri_formatter.rb	(revision 43369)
@@ -1,13 +1,30 @@ https://github.com/ruby/ruby/blob/trunk/lib/rubygems/uri_formatter.rb#L1
 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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/uri_formatter.rb#L37
     (@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
Index: lib/rubygems/user_interaction.rb
===================================================================
--- lib/rubygems/user_interaction.rb	(revision 43368)
+++ lib/rubygems/user_interaction.rb	(revision 43369)
@@ -66,9 +66,13 @@ module Gem::DefaultUserInteraction https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L66
 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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L88
 
   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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L159
 
 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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L187
     @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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L365
   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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L418
   # 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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L452
 
     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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L497
 
     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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L553
   # 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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L585
   # 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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L622
       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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L638
       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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/user_interaction.rb#L648
 
     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
Index: lib/rubygems/psych_additions.rb
===================================================================
--- lib/rubygems/psych_additions.rb	(revision 43368)
+++ lib/rubygems/psych_additions.rb	(revision 43369)
@@ -4,6 +4,6 @@ https://github.com/ruby/ruby/blob/trunk/lib/rubygems/psych_additions.rb#L4
 # blows up.
 
 module Psych # :nodoc:
-  class PrivateType
+  class PrivateType # :nodoc:
   end
 end
Index: lib/rubygems/core_ext/kernel_gem.rb
===================================================================
--- lib/rubygems/core_ext/kernel_gem.rb	(revision 43368)
+++ lib/rubygems/core_ext/kernel_gem.rb	(revision 43369)
@@ -1,3 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/lib/rubygems/core_ext/kernel_gem.rb#L1
+##
+# 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.
Index: lib/rubygems/version.rb
===================================================================
--- lib/rubygems/version.rb	(revision 43368)
+++ lib/rubygems/version.rb	(revision 43369)
@@ -174,8 +174,6 @@ class Gem::Version https://github.com/ruby/ruby/blob/trunk/lib/rubygems/version.rb#L174
   #   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 https://github.com/ruby/ruby/blob/trunk/lib/rubygems/version.rb#L186
 
   @@all = {}
 
-  def self.new version
+  def self.new version # :nodoc:
     @@all[version] ||= super
   end
 
@@ -255,17 +253,17 @@ class Gem::Version https://github.com/ruby/ruby/blob/trunk/lib/rubygems/version.rb#L253
     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
 
Index: lib/rubygems/uninstaller.rb
=============================================================== (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

[前][次][番号順一覧][スレッド一覧]