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/