diff --git a/ChangeLog b/ChangeLog index 4ea88fb239..7b98496392 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +Sun Oct 20 10:32:48 2013 Eric Hodel + + * 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 * lib/rubygems: Update to RubyGems master 3de7e0f. Changes: 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 $LOAD_PATH. 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