* lib/irb.rb, lib/irb/*: Documentation for IRB

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38515 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 42 insertions, 6 deletions

diff --git a/lib/irb/inspector.rb b/lib/irb/inspector.rb
index 6e93d3ccb9..94f42d5217 100644
--- a/lib/irb/inspector.rb
+++ b/lib/irb/inspector.rb
@@ -12,37 +12,73 @@
 
 module IRB # :nodoc:
 
+
+  # Convenience method to create a new Inspector, using the given +inspect+
+  # proc, and optional +init+ proc and passes them to Inspector.new
+  #
+  #     irb(main):001:0> ins = IRB::Inspector(proc{ |v| "omg! #{v}" })
+  #     irb(main):001:0> IRB.CurrentContext.inspect_mode = ins # => omg! #<IRB::Inspector:0x007f46f7ba7d28>
+  #     irb(main):001:0> "what?" #=> omg! what?
+  #
   def IRB::Inspector(inspect, init = nil)
     Inspector.new(inspect, init)
   end
 
+  # An irb inspector
+  #
+  # In order to create your own custom inspector there are two things you
+  # should be aware of:
+  #
+  # Inspector uses #inspect_value, or +inspect_proc+, for output of return values.
+  #
+  # This also allows for an optional #init+, or +init_proc+, which is called
+  # when the inspector is activated.
+  #
+  # Knowing this, you can create a rudimentary inspector as follows:
+  #
+  #     irb(main):001:0> ins = IRB::Inspector.new(proc{ |v| "omg! #{v}" })
+  #     irb(main):001:0> IRB.CurrentContext.inspect_mode = ins # => omg! #<IRB::Inspector:0x007f46f7ba7d28>
+  #     irb(main):001:0> "what?" #=> omg! what?
+  #
   class Inspector
+    # Creates a new inspector object, using the given +inspect_proc+ when
+    # output return values in irb.
     def initialize(inspect_proc, init_proc = nil)
       @init = init_proc
       @inspect = inspect_proc
     end
 
+    # Proc to call when the inspector is activated, good for requiring
+    # dependant libraries.
     def init
       @init.call if @init
     end
 
+    # Proc to call when the input is evaluated and output in irb.
     def inspect_value(v)
       @inspect.call(v)
     end
   end
 
+  # Default inspectors available to irb, this includes:
+  #
+  # +:pp+::       Using Kernel#pretty_inspect
+  # +:yaml+::     Using YAML.dump
+  # +:marshal+::  Using Marshal.dump
   INSPECTORS = {}
 
+  # Determines the inspector to use where +inspector+ is one of the keys passed
+  # during inspector definition.
   def INSPECTORS.keys_with_inspector(inspector)
     select{|k,v| v == inspector}.collect{|k, v| k}
   end
 
-  # ex)
-  # INSPECTORS.def_inspector(key, init_p=nil){|v| v.inspect}
-  # INSPECTORS.def_inspector([key1,..], init_p=nil){|v| v.inspect}
-  # INSPECTORS.def_inspector(key, inspector)
-  # INSPECTORS.def_inspector([key1,...], inspector)
-
+  # Example
+  #
+  #     INSPECTORS.def_inspector(key, init_p=nil){|v| v.inspect}
+  #     INSPECTORS.def_inspector([key1,..], init_p=nil){|v| v.inspect}
+  #     INSPECTORS.def_inspector(key, inspector)
+  #     INSPECTORS.def_inspector([key1,...], inspector)
   def INSPECTORS.def_inspector(key, arg=nil, &block)
 #     if !block_given?
 #       case arg