another doc update, documented completion.rb and reworded some sections in README

README.markdown

@@ -6,11 +6,10 @@ Pry
 _attach an irb-like session to any object at runtime_
 
 Pry is a simple Ruby REPL (Read-Eval-Print-Loop) that specializes in the interactive
-manipulation of objects during the running of a program. It is primarily
-designed for examining and manipulating large and complicated runtime state.
+manipulation of objects during the running of a program. 
 
 It is not based on the IRB codebase, and implements some unique REPL
-commands such as `show_method` and `jump_to`
+commands such as `show_method` and `show_doc`
 
 * Install the [gem](https://rubygems.org/gems/pry): `gem install pry`
 * Read the [documentation](http://rdoc.info/github/banister/pry/master/file/README.markdown)
@@ -64,7 +63,7 @@ OR
     beginning Pry session for 6
     pry(6)>
 
-Example: Pry sessions can nest arbitrarily deep
+Example: Pry sessions can nest
 -----------------------------------------------
 
 Here we will begin Pry at top-level, then pry on a class and then on
@@ -455,7 +454,7 @@ the state of the object. E.g, the "ls" command is implemented as follows
 
 #### The opts hash
 
-These are miscellaneous variables that may be useful to your own commands:
+These are miscellaneous variables that may be useful to your commands:
 
 * `opts[:val]` - The line of input that invoked the command.
 * `opts[:eval_string]` - The cumulative lines of input for multi-line input.

lib/pry/completion.rb

@@ -3,6 +3,8 @@
 require "readline"
 
 class Pry
+
+  # Implements tab completion for Readline in Pry
   module InputCompleter
     
     if Readline.respond_to?("basic_word_break_characters=")
@@ -35,6 +37,9 @@ class Pry
                  "<", "<<", "<=", "<=>", "==", "===", "=~", ">", ">=", ">>",
                  "[]", "[]=", "^", "!", "!=", "!~"]
 
+    # Return a new completion proc for use by Readline.
+    # @param [Binding] target The current binding context.
+    # @param [Array<String>] commands The array of Pry commands.
     def self.build_completion_proc(target, commands=[""])
       proc do |input|
         bind = target

lib/pry/pry_instance.rb

@@ -125,6 +125,7 @@ class Pry
     target = binding_for(target)
 
     if input == Readline
+      # Readline tab completion
       Readline.completion_proc = Pry::InputCompleter.build_completion_proc(target, commands.commands.keys)
     end
 
@@ -204,21 +205,17 @@ class Pry
       commands.target = target
       commands.output = output
 
-      # send the correct number of parameters to the block (to avoid
-      # warnings in 1.8.7)
       case action.arity <=> 0
       when -1
 
+        # Use instance_exec() to make the `opts` method, etc available
         commands.instance_exec(*args, &action)
       when 1, 0
 
-        # ensure that we get the right number of parameters;
-        # using values_at we pad out missing parameters with nils so
-        # that 1.8.7 doesn't complain about incorrect arity (1.9.2
+        # ensure that we get the right number of parameters
+        # since 1.8.7 complains about incorrect arity (1.9.2
         # doesn't care)
         args_with_corrected_arity = args.values_at *0..(action.arity - 1)
-
-        # Use instance_exec() to make the `opts` method, etc available
         commands.instance_exec(*args_with_corrected_arity, &action)
       end