updated docs

lib/pry/pry_class.rb

@@ -1,18 +1,81 @@
+# @author John Mair (banisterfiend)
 class Pry
 
   # class accessors
   class << self
+
+    # Get nesting data.
+    # This method should not need to be accessed directly.
+    # @return [Array] The unparsed nesting information.
     attr_reader :nesting
-    attr_accessor :last_result, :active_instance
-    attr_accessor :input, :output
-    attr_accessor :commands, :print, :hooks
+
+    # Get last value evaluated by Pry.
+    # This method should not need to be accessed directly.
+    # @return [Object] The last result.
+    attr_accessor :last_result
+
+    # Get the active Pry instance that manages the active Pry session.
+    # This method should not need to be accessed directly.
+    # @return [Pry] The active Pry instance.
+    attr_accessor :active_instance
+    
+    # Set/Get the object to use for input by default by all Pry instances.
+    # (see input.rb)
+    # @return [#read] The object to use for input by default by all
+    #   Pry instances.
+    attr_accessor :input
+
+    # Set/Get the object to use for output by default by all Pry instances.
+    # (see: output.rb)
+    # @return [#puts] The object to use for output by default by all
+    #   Pry instances.
+    attr_accessor :output
+
+    # Set/Get the object to use for commands by default by all Pry instances.
+    # (see commands.rb)
+    # @return [#commands] The object to use for commands by default by all
+    #   Pry instances.
+    attr_accessor :commands
+
+    # Set/Get the Proc to use for printing by default by all Pry
+    # instances.
+    # This is the 'print' componenent of the REPL.
+    # (see print.rb)
+    # @return [Proc] The Proc to use for printing by default by all
+    #   Pry instances.
+    attr_accessor :print
+
+    
+    # Set/Get the Hash that defines Pry hooks used by default by all Pry
+    # instances.
+    # (see print.rb)
+    # @return [Hash] The hooks used by default by all Pry instances.
+    # @example
+    #   Pry.hooks :before_session => proc { puts "hello" },
+    #     :after_session => proc { puts "goodbye" }
+    attr_accessor :hooks
+
+    # Set/Get the array of Procs to be used for the prompts by default by
+    # all Pry instances.
+    # (see prompts.rb)
+    # @return [Array<Proc>] The array of Procs to be used for the
+    #   prompts by default by all Pry instances.
     attr_accessor :default_prompt
   end
 
+  # Start a Pry REPL.
+  # @param [Object, Binding] target The receiver of the Pry session
+  # @param options (see Pry#initialize)
+  # @example
+  #   Pry.start(Object.new, :input => MyInput.new)
   def self.start(target=TOPLEVEL_BINDING, options={})
     new(options).repl(target)
   end
 
+  # A custom version of `Kernel#inspect`.
+  # This method should not need to be accessed directly.
+  # @param obj The object to view.
+  # @return [String] The string representation of `obj`.
   def self.view(obj)
     case obj
     when String, Hash, Array, Symbol, nil
@@ -22,6 +85,7 @@ class Pry
     end
   end
 
+  # Set all the configurable options back to their default values
   def self.reset_defaults
     @input = Input.new
     @output = Output.new

lib/pry/pry_instance.rb

@@ -1,31 +1,55 @@
 class Pry
 
+  # The list of configuration options.
   ConfigOptions = [:input, :output, :commands, :print,
                    :default_prompt, :hooks]
 
   attr_accessor *ConfigOptions
   
+  # Create a new `Pry` object.
+  # @param [Hash] options The optional configuration parameters.
+  # @option options [#read] :input The object to use for input. (see input.rb)
+  # @option options [#puts] :output The object to use for output. (see output.rb)
+  # @option options [#commands] :commands The object to use for 
+  #   commands. (see commands.rb)
+  # @options options [Hash] :hooks The defined hook Procs (see hooks.rb)
+  # @option options [Array<Proc>] :default_prompt The array of Procs
+  #   to use for the prompts.
+  # @option options [Proc] :print The Proc to use for the 'print' componenent of the REPL
   def initialize(options={})
 
-    options = ConfigOptions.each_with_object({}) { |v, h| h[v] = Pry.send(v) }
-    options.merge!(options)
+    default_options = ConfigOptions.each_with_object({}) { |v, h| h[v] = Pry.send(v) }
+    default_options.merge!(options)
 
     ConfigOptions.each do |key|
-      instance_variable_set("@#{key}", options[key])
+      instance_variable_set("@#{key}", default_options[key])
     end
   end
 
+  # Get nesting data.
+  # This method should not need to be accessed directly.
+  # @return [Array] The unparsed nesting information.
   def nesting
     self.class.nesting
   end
 
+  # Set nesting data.
+  # This method should not need to be accessed directly.
+  # @param v nesting data.
   def nesting=(v)
     self.class.nesting = v
   end
+
+  # Execute the hook `hook_name`, if it is defined.
+  # @param [Symbol] hook_name The hook to execute
+  # @param [Array] args The arguments to pass to the hook.
+  def exec_hook(hook_name, *args, &block)
+    hooks[hook_name].call(*args, &block) if hooks[hook_name]
+  end
   
-  # Start a read-eval-print-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
+  # @param [Object, Binding] target The receiver of the Pry session
   # @return [Object] The target of the Pry session
   # @example
   #   Pry.new.repl(Object.new)
@@ -33,7 +57,7 @@ class Pry
     target = binding_for(target)
     target_self = target.eval('self')
 
-    hooks[:before_session].call(output, target_self)
+    exec_hook :before_session, output, target_self
     
     nesting_level = nesting.size
 
@@ -51,7 +75,8 @@ class Pry
     end
 
     nesting.pop
-    hooks[:after_session].call(output, target_self)
+    
+    exec_hook :after_session, output, target_self
 
     # we only enter here if :breakout has been thrown
     if nesting_level != break_level
@@ -61,9 +86,9 @@ class Pry
     target_self
   end
   
-  # Perform a read-eval-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
+  # @param [Object, Binding] target The receiver of the read-eval-print
   # @example
   #   Pry.new.rep(Object.new)
   def rep(target=TOPLEVEL_BINDING)
@@ -73,9 +98,8 @@ class Pry
 
   # 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.
+  # @param [Object, Binding] 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)
@@ -95,7 +119,7 @@ class Pry
   # 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.
+  # @param [Object, Binding] target The receiver of the read.
   # @return [String] The Ruby expression.
   # @example
   #   Pry.new.r(Object.new)
@@ -116,10 +140,10 @@ class Pry
   # 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] 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
+  #   multi-line input.
+  # @param [Object] target The receiver of the commands.
   def process_commands(val, eval_string, target)
     def eval_string.clear() replace("") end
 
@@ -142,7 +166,7 @@ class Pry
   # 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
+  #   multi-line input.
   # @param [Object] target The receiver of the Pry session.
   # @return [String] The prompt.
   def prompt(eval_string, target)
@@ -159,7 +183,7 @@ class Pry
     require 'ripper'
 
     # Determine if a string of code is a valid Ruby expression.
-    # Ruby 1.9 uses Ripper parser.
+    # Ruby 1.9 uses Ripper, Ruby 1.8 uses RubyParser.
     # @param [String] code The code to validate.
     # @return [Boolean] Whether or not the code is a valid Ruby expression.
     # @example
@@ -173,7 +197,7 @@ class Pry
     require 'ruby_parser'
     
     # Determine if a string of code is a valid Ruby expression.
-    # Ruby 1.8 uses RubyParser parser.
+    # Ruby 1.9 uses Ripper, Ruby 1.8 uses RubyParser.
     # @param [String] code The code to validate.
     # @return [Boolean] Whether or not the code is a valid Ruby expression.
     # @example