1 files changed, 9 insertions, 3 deletions
diff --git a/object.c b/object.c
index 660c9e1fe1..5bb9a7cd03 100644
--- a/object.c
+++ b/object.c
@@ -448,9 +448,15 @@ rb_obj_is_kind_of(VALUE obj, VALUE c)
  *  call-seq:
  *     obj.tap{|x|...}    => obj
  *  
- *  Returns the receiver after executing the block given.  Its main
- *  purpose is to be inseted in the method chain.
- *     
+ *  Yields <code>x</code> to the block, and then returns <code>x</code>.
+ *  The primary purpose of this method is to "tap into" a method chain,
+ *  in order to perform operations on intermediate results within the chain.
+ *
+ *	(1..10)                .tap {|x| puts "original: #{x.inspect}"}
+ *	  .to_a                .tap {|x| puts "array: #{x.inspect}"}
+ *	  .select {|x| x%2==0} .tap {|x| puts "evens: #{x.inspect}"}
+ *	  .map { |x| x*x }     .tap {|x| puts "squares: #{x.inspect}"}
+ *
  */
 
 VALUE