* proc.c: Rdoc formatting, clarification & example fix

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

proc.c

@@ -128,39 +128,39 @@ proc_clone(VALUE self)
  * call-seq:
  *   prc.lambda? -> true or false
  *
- * Returns true for a Proc object which argument handling is rigid.
- * Such procs are typically generated by lambda.
+ * Returns +true+ for a Proc object for which argument handling is rigid.
+ * Such procs are typically generated by +lambda+.
  *
- * A Proc object generated by proc ignore extra arguments.
+ * A Proc object generated by +proc+ ignores extra arguments.
  *
  *   proc {|a,b| [a,b] }.call(1,2,3)    #=> [1,2]
  *
- * It provides nil for lacked arguments.
+ * It provides +nil+ for missing arguments.
  *
  *   proc {|a,b| [a,b] }.call(1)        #=> [1,nil]
  *
- * It expand single-array argument.
+ * It expands a single array argument.
  *
  *   proc {|a,b| [a,b] }.call([1,2])    #=> [1,2]
  *
- * A Proc object generated by lambda doesn't have such tricks.
+ * A Proc object generated by +lambda+ doesn't have such tricks.
  *
  *   lambda {|a,b| [a,b] }.call(1,2,3)  #=> ArgumentError
  *   lambda {|a,b| [a,b] }.call(1)      #=> ArgumentError
  *   lambda {|a,b| [a,b] }.call([1,2])  #=> ArgumentError
  *
  * Proc#lambda? is a predicate for the tricks.
- * It returns true if no tricks.
+ * It returns +true+ if no tricks apply.
  *
  *   lambda {}.lambda?            #=> true
  *   proc {}.lambda?              #=> false
  *
- * Proc.new is same as proc.
+ * Proc.new is the same as +proc+.
  *
  *   Proc.new {}.lambda?          #=> false
  *
- * lambda, proc and Proc.new preserves the tricks of
- * a Proc object given by & argument.
+ * +lambda+, +proc+ and Proc.new preserve the tricks of
+ * a Proc object given by <code>&</code> argument.
  *
  *   lambda(&lambda {}).lambda?   #=> true
  *   proc(&lambda {}).lambda?     #=> true
@@ -170,13 +170,13 @@ proc_clone(VALUE self)
  *   proc(&proc {}).lambda?       #=> false
  *   Proc.new(&proc {}).lambda?   #=> false
  *
- * A Proc object generated by & argument has the tricks
+ * A Proc object generated by <code>&</code> argument has the tricks
  *
  *   def n(&b) b.lambda? end
  *   n {}                         #=> false
  *
- * The & argument preserves the tricks if a Proc object is given
- * by & argument.
+ * The <code>&</code> argument preserves the tricks if a Proc object
+ * is given by <code>&</code> argument.
  *
  *   n(&lambda {})                #=> true
  *   n(&proc {})                  #=> false
@@ -190,18 +190,18 @@ proc_clone(VALUE self)
  *   n(&method(:m))               #=> true
  *   n(&method(:m).to_proc)       #=> true
  *
- * define_method is treated same as method definition.
+ * +define_method+ is treated the same as method definition.
  * The defined method has no tricks.
  *
  *   class C
  *     define_method(:d) {}
  *   end
- *   C.new.e(1,2)       #=> ArgumentError
+ *   C.new.d(1,2)       #=> ArgumentError
  *   C.new.method(:d).to_proc.lambda?   #=> true
  *
- * define_method always defines a method without the tricks,
+ * +define_method+ always defines a method without the tricks,
  * even if a non-lambda Proc object is given.
- * This is the only exception which the tricks are not preserved.
+ * This is the only exception for which the tricks are not preserved.
  *
  *   class C
  *     define_method(:e, &proc {})
@@ -209,20 +209,19 @@ proc_clone(VALUE self)
  *   C.new.e(1,2)       #=> ArgumentError
  *   C.new.method(:e).to_proc.lambda?   #=> true
  *
- * This exception is for a wrapper of define_method.
- * It eases defining a method defining method which defines a usual method which has no tricks.
+ * This exception insures that methods never have tricks
+ * and makes it easy to have wrappers to define methods that behave as usual.
  *
- *   class << C
- *     def def2(name, &body)
+ *   class C
+ *     def self.def2(name, &body)
  *       define_method(name, &body)
  *     end
- *   end
- *   class C
+ *
  *     def2(:f) {}
  *   end
  *   C.new.f(1,2)       #=> ArgumentError
  *
- * The wrapper, def2, defines a method which has no tricks.
+ * The wrapper <i>def2</i> defines a method which has no tricks.
  *
  */
 
@@ -335,7 +334,7 @@ rb_binding_new(void)
  *  Returns a +Binding+ object, describing the variable and
  *  method bindings at the point of call. This object can be used when
  *  calling +eval+ to execute the evaluated command in this
- *  environment. Also see the description of class +Binding+.
+ *  environment. See also the description of class +Binding+.
  *
  *     def get_binding(param)
  *       return binding
@@ -699,8 +698,8 @@ iseq_location(rb_iseq_t *iseq)
  * call-seq:
  *    prc.source_location  -> [String, Fixnum]
  *
- * returns the ruby source filename and line number containing this proc
- * or nil if this proc was not defined in ruby (i.e. native)
+ * Returns the Ruby source filename and line number containing this proc
+ * or +nil+ if this proc was not defined in Ruby (i.e. native)
  */
 
 VALUE
@@ -730,12 +729,12 @@ unnamed_parameters(int arity)
 
 /*
  * call-seq:
- *    proc.parameters  -> array
+ *    prc.parameters  -> array
  *
- * returns the parameter information of this proc.
+ * Returns the parameter information of this proc.
  *
- *    prc = lambda{|x, y=42, *rest|}
- *    prc.parameters  #=> [[:req, :x], [:opt, :y], [:rest, :rest]]
+ *    prc = lambda{|x, y=42, *other|}
+ *    prc.parameters  #=> [[:req, :x], [:opt, :y], [:rest, :other]]
  */
 
 static VALUE
@@ -753,7 +752,7 @@ rb_proc_parameters(VALUE self)
  * call-seq:
  *   prc == other_proc   ->  true or false
  *
- * Return <code>true</code> if <i>prc</i> is the same object as
+ * Returns <code>true</code> if <i>prc</i> is the same object as
  * <i>other_proc</i>, or if they are both procs with the same body.
  */
 
@@ -784,7 +783,7 @@ proc_eq(VALUE self, VALUE other)
  * call-seq:
  *   prc.hash   ->  integer
  *
- * Return hash value corresponding to proc body.
+ * Returns a hash value corresponding to proc body.
  */
 
 static VALUE
@@ -804,7 +803,7 @@ proc_hash(VALUE self)
  * call-seq:
  *   prc.to_s   -> string
  *
- * Shows the unique identifier for this proc, along with
+ * Returns the unique identifier for this proc, along with
  * an indication of where the proc was defined.
  */
 
@@ -1049,7 +1048,7 @@ method_eq(VALUE method, VALUE other)
  * call-seq:
  *    meth.hash   -> integer
  *
- * Return a hash value corresponding to the method object.
+ * Returns a hash value corresponding to the method object.
  */
 
 static VALUE
@@ -1071,7 +1070,7 @@ method_hash(VALUE method)
  *  call-seq:
  *     meth.unbind    -> unbound_method
  *
- *  Dissociates <i>meth</i> from it's current receiver. The resulting
+ *  Dissociates <i>meth</i> from its current receiver. The resulting
  *  <code>UnboundMethod</code> can subsequently be bound to a new object
  *  of the same class (see <code>UnboundMethod</code>).
  */
@@ -1695,8 +1694,8 @@ rb_method_get_iseq(VALUE method)
  * call-seq:
  *    meth.source_location  -> [String, Fixnum]
  *
- * returns the ruby source filename and line number containing this method
- * or nil if this method was not defined in ruby (i.e. native)
+ * Returns the Ruby source filename and line number containing this method
+ * or nil if this method was not defined in Ruby (i.e. native)
  */
 
 VALUE
@@ -1715,7 +1714,7 @@ rb_method_location(VALUE method)
  * call-seq:
  *    meth.parameters  -> array
  *
- * returns the parameter information of this method
+ * Returns the parameter information of this method.
  */
 
 static VALUE
@@ -1733,7 +1732,7 @@ rb_method_parameters(VALUE method)
  *   meth.to_s      ->  string
  *   meth.inspect   ->  string
  *
- *  Show the name of the underlying method.
+ *  Returns the name of the underlying method.
  *
  *    "cat".method(:count).inspect   #=> "#<Method: String#count>"
  */