1 files changed, 73 insertions, 41 deletions

diff --git a/lib/rubygems/gemcutter_utilities.rb b/lib/rubygems/gemcutter_utilities.rb
index 04d7cd300f..9dbc18ba98 100644
--- a/lib/rubygems/gemcutter_utilities.rb
+++ b/lib/rubygems/gemcutter_utilities.rb
@@ -1,11 +1,17 @@
 require 'rubygems/remote_fetcher'
 
+##
+# Utility methods for using the RubyGems API.
+
 module Gem::GemcutterUtilities
+
   # TODO: move to Gem::Command
   OptionParser.accept Symbol do |value|
     value.to_sym
   end
 
+  attr_writer :host
+
   ##
   # Add the --key option
 
@@ -17,6 +23,9 @@ module Gem::GemcutterUtilities
     end
   end
 
+  ##
+  # The API key from the command options or from the user's configuration.
+
   def api_key
     if options[:key] then
       verify_api_key options[:key]
@@ -27,35 +36,10 @@ module Gem::GemcutterUtilities
     end
   end
 
-  def sign_in sign_in_host = self.host
-    return if Gem.configuration.rubygems_api_key
-
-    pretty_host = if Gem::DEFAULT_HOST == sign_in_host then
-                    'RubyGems.org'
-                  else
-                    sign_in_host
-                  end
-
-    say "Enter your #{pretty_host} credentials."
-    say "Don't have an account yet? " +
-        "Create one at #{sign_in_host}/sign_up"
-
-    email    =              ask "   Email: "
-    password = ask_for_password "Password: "
-    say "\n"
-
-    response = rubygems_api_request(:get, "api/v1/api_key",
-                                    sign_in_host) do |request|
-      request.basic_auth email, password
-    end
-
-    with_response response do |resp|
-      say "Signed in."
-      Gem.configuration.rubygems_api_key = resp.body
-    end
-  end
+  ##
+  # The host to connect to either from the RUBYGEMS_HOST environment variable
+  # or from the user's configuration
 
-  attr_writer :host
   def host
     configured_host = Gem.host unless
       Gem.configuration.disable_default_gem_server
@@ -70,6 +54,9 @@ module Gem::GemcutterUtilities
       end
   end
 
+  ##
+  # Creates an RubyGems API to +host+ and +path+ with the given HTTP +method+.
+
   def rubygems_api_request(method, path, host = nil, &block)
     require 'net/http'
 
@@ -86,23 +73,43 @@ module Gem::GemcutterUtilities
     Gem::RemoteFetcher.fetcher.request(uri, request_method, &block)
   end
 
-  def with_response resp, error_prefix = nil
-    case resp
-    when Net::HTTPSuccess then
-      if block_given? then
-        yield resp
-      else
-        say resp.body
-      end
-    else
-      message = resp.body
-      message = "#{error_prefix}: #{message}" if error_prefix
+  ##
+  # Signs in with the RubyGems API at +sign_in_host+ and sets the rubygems API
+  # key.
 
-      say message
-      terminate_interaction 1 # TODO: question this
+  def sign_in sign_in_host = nil
+    sign_in_host ||= self.host
+    return if Gem.configuration.rubygems_api_key
+
+    pretty_host = if Gem::DEFAULT_HOST == sign_in_host then
+                    'RubyGems.org'
+                  else
+                    sign_in_host
+                  end
+
+    say "Enter your #{pretty_host} credentials."
+    say "Don't have an account yet? " +
+        "Create one at #{sign_in_host}/sign_up"
+
+    email    =              ask "   Email: "
+    password = ask_for_password "Password: "
+    say "\n"
+
+    response = rubygems_api_request(:get, "api/v1/api_key",
+                                    sign_in_host) do |request|
+      request.basic_auth email, password
+    end
+
+    with_response response do |resp|
+      say "Signed in."
+      Gem.configuration.rubygems_api_key = resp.body
     end
   end
 
+  ##
+  # Retrieves the pre-configured API key +key+ or terminates interaction with
+  # an error.
+
   def verify_api_key(key)
     if Gem.configuration.api_keys.key? key then
       Gem.configuration.api_keys[key]
@@ -112,4 +119,29 @@ module Gem::GemcutterUtilities
     end
   end
 
+  ##
+  # If +response+ is an HTTP Success (2XX) response, yields the response if a
+  # block was given or shows the response body to the user.
+  #
+  # If the response was not successful, shows an error to the user including
+  # the +error_prefix+ and the response body.
+
+  def with_response response, error_prefix = nil
+    case response
+    when Net::HTTPSuccess then
+      if block_given? then
+        yield response
+      else
+        say response.body
+      end
+    else
+      message = response.body
+      message = "#{error_prefix}: #{message}" if error_prefix
+
+      say message
+      terminate_interaction 1 # TODO: question this
+    end
+  end
+
 end
+