start at docs

lib/pry/prompts.rb

@@ -1,5 +1,5 @@
 class Pry
-  DEFAULT_PROMPT = [
+  STANDARD_PROMPT = [
                     proc do |v, nest|
                       if nest == 0
                         "pry(#{Pry.view(v)})> "

lib/pry/pry_class.rb

@@ -8,7 +8,7 @@ class Pry
     attr_accessor :commands, :print, :hooks
     attr_accessor :default_prompt
   end
-  
+
   def self.start(target=TOPLEVEL_BINDING, options={})
     new(options).repl(target)
   end
@@ -26,7 +26,7 @@ class Pry
     @input = Input.new
     @output = Output.new
     @commands = Commands.new(@output)
-    @default_prompt = DEFAULT_PROMPT
+    @default_prompt = STANDARD_PROMPT
     @print = DEFAULT_PRINT
     @hooks = DEFAULT_HOOKS
   end

lib/pry/pry_instance.rb

@@ -23,7 +23,12 @@ class Pry
     self.class.nesting = v
   end
   
-  # loop
+  # Start a read-eval-print-loop
+  # If no parameter is given, default to top-level (main).
+  # @param [Object] target The receiver of the Pry session
+  # @return [Object] The target of the Pry session
+  # @example
+  #   Pry.new.repl(Object.new)
   def repl(target=TOPLEVEL_BINDING)
     target = binding_for(target)
     target_self = target.eval('self')
@@ -56,13 +61,23 @@ class Pry
     target_self
   end
   
-  # print
+  # Perform a read-eval-print
+  # If no parameter is given, default to top-level (main).
+  # @param [Object] target The receiver of the read-eval-print
+  # @example
+  #   Pry.new.rep(Object.new)
   def rep(target=TOPLEVEL_BINDING)
     target = binding_for(target)
     print.call output, re(target)
   end
 
-  # eval
+  # Perform a read-eval
+  # If no parameter is given, default to top-level (main).
+  # @param [Object] target The receiver of the read-eval-print
+  # @return [Object] The result of the eval or an `Exception` object
+  # in case of error.
+  # @example
+  #   Pry.new.re(Object.new)
   def re(target=TOPLEVEL_BINDING)
     target = binding_for(target)
     Pry.last_result = target.eval r(target)
@@ -75,12 +90,20 @@ class Pry
     e
   end
 
-  # read
+  # Perform a read.
+  # If no parameter is given, default to top-level (main).
+  # This is a multi-line read; so the read continues until a valid
+  # Ruby expression is received.
+  # Pry commands are also accepted here and operate on the target.
+  # @param [Object] target The receiver of the read.
+  # @return [String] The Ruby expression.
+  # @example
+  #   Pry.new.r(Object.new)
   def r(target=TOPLEVEL_BINDING)
     target = binding_for(target)
     eval_string = ""
     loop do
-      val = input.read(prompt(eval_string, target, nesting.level))
+      val = input.read(prompt(eval_string, target))
       eval_string << "#{val.chomp}\n"
       process_commands(val, eval_string, target)
       
@@ -88,6 +111,15 @@ class Pry
     end
   end
   
+  # Process Pry commands. Pry commands are not Ruby methods and are evaluated
+  # prior to Ruby expressions.
+  # Commands can be modified/configured by the user: see `Pry::Commands`
+  # This method should not need to be invoked directly - it is called
+  # by `Pry#r`
+  # @param [String] val The current line of input
+  # @param [String] eval_string The cumulative lines of input for
+  # multi-line input
+  # @param [Object] target The receiver of the commands
   def process_commands(val, eval_string, target)
     def eval_string.clear() replace("") end
 
@@ -107,19 +139,32 @@ class Pry
     end
   end
 
-  def prompt(eval_string, target, nest)
+  # Returns the appropriate prompt to use.
+  # This method should not need to be invoked directly.
+  # @param [String] eval_string The cumulative lines of input for
+  # multi-line input
+  # @param [Object] target The receiver of the Pry session.
+  # @return [String] The prompt.
+  def prompt(eval_string, target)
     target_self = target.eval('self')
     
     if eval_string.empty?
-      default_prompt.first.call(target_self, nest)
+      default_prompt.first.call(target_self, nesting.level)
     else
-      default_prompt.last.call(target_self, nest)
+      default_prompt.last.call(target_self, nesting.level)
     end
   end
 
   if RUBY_VERSION =~ /1.9/
     require 'ripper'
-    
+
+    # Determine if a string of code is a valid Ruby expression.
+    # Ruby 1.9 uses Ripper parser.
+    # @param [String] code The code to validate.
+    # @return [Boolean] Whether or not the code is a valid Ruby expression.
+    # @example
+    #   valid_expression?("class Hello") #=> false
+    #   valid_expression?("class Hello; end") #=> true
     def valid_expression?(code)
       !!Ripper::SexpBuilder.new(code).parse
     end
@@ -127,6 +172,13 @@ class Pry
   else
     require 'ruby_parser'
     
+    # Determine if a string of code is a valid Ruby expression.
+    # Ruby 1.8 uses RubyParser parser.
+    # @param [String] code The code to validate.
+    # @return [Boolean] Whether or not the code is a valid Ruby expression.
+    # @example
+    #   valid_expression?("class Hello") #=> false
+    #   valid_expression?("class Hello; end") #=> true
     def valid_expression?(code)
       RubyParser.new.parse(code)
     rescue Racc::ParseError, SyntaxError
@@ -136,6 +188,12 @@ class Pry
     end
   end
 
+  
+  # Return a `Binding` object for `target` or return `target` if it is
+  # already a `Binding`.
+  # In the case where `target` is top-level then return `TOPLEVEL_BINDING`
+  # @param [Object] target The object to get a `Binding` object for.
+  # @return [Binding] The `Binding` object.
   def binding_for(target)
     if target.is_a?(Binding)
       target