merge revision(s) 57765: [Backport #13273]

	proc.c: documentation for Proc#{call,yield,[]}

	* proc.c: [DOC] fix and improve docs for Proc#{call,yield,[]}:

	  * change order of Document-method directives as workaround for an
	    RDoc rendering problem where the documentation for Proc#call displays
	    a "Document-method: []" code block.  [ruby-core:79887] [Bug #13273]
	  * add missing call-seq and example for Proc#yield
	  * remove pointless cross reference to Proc#yield
	  * update description for handling of extra or missing arguments,
	    improve examples and add cross reference to #lambda?

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

2 files changed, 24 insertions, 20 deletions

diff --git a/proc.c b/proc.c
index 3ddbe3e2e3..4f3fdc50ed 100644
--- a/proc.c
+++ b/proc.c
@@ -674,38 +674,42 @@ rb_block_clear_env_self(VALUE proc)
 /* CHECKME: are the argument checking semantics correct? */
 
 /*
+ *  Document-method: []
+ *  Document-method: call
+ *  Document-method: yield
+ *
  *  call-seq:
  *     prc.call(params,...)   -> obj
  *     prc[params,...]        -> obj
  *     prc.(params,...)       -> obj
+ *     prc.yield(params,...)  -> obj
  *
  *  Invokes the block, setting the block's parameters to the values in
  *  <i>params</i> using something close to method calling semantics.
- *  Generates a warning if multiple values are passed to a proc that
- *  expects just one (previously this silently converted the parameters
- *  to an array).  Note that prc.() invokes prc.call() with the parameters
- *  given.  It's a syntax sugar to hide "call".
+ *  Returns the value of the last expression evaluated in the block.
  *
- *  For procs created using <code>lambda</code> or <code>->()</code> an error
- *  is generated if the wrong number of parameters are passed to a Proc with
- *  multiple parameters.  For procs created using <code>Proc.new</code> or
- *  <code>Kernel.proc</code>, extra parameters are silently discarded.
+ *     a_proc = Proc.new {|scalar, *values| values.map {|value| value*scalar } }
+ *     a_proc.call(9, 1, 2, 3)    #=> [9, 18, 27]
+ *     a_proc[9, 1, 2, 3]         #=> [9, 18, 27]
+ *     a_proc.(9, 1, 2, 3)        #=> [9, 18, 27]
+ *     a_proc.yield(9, 1, 2, 3)   #=> [9, 18, 27]
  *
- *  Returns the value of the last expression evaluated in the block. See
- *  also <code>Proc#yield</code>.
+ *  Note that <code>prc.()</code> invokes <code>prc.call()</code> with
+ *  the parameters given.  It's syntactic sugar to hide "call".
  *
- *     a_proc = Proc.new {|a, *b| b.collect {|i| i*a }}
- *     a_proc.call(9, 1, 2, 3)   #=> [9, 18, 27]
- *     a_proc[9, 1, 2, 3]        #=> [9, 18, 27]
- *     a_proc = lambda {|a,b| a}
- *     a_proc.call(1,2,3)
+ *  For procs created using <code>lambda</code> or <code>->()</code> an error
+ *  is generated if the wrong number of parameters are passed to the proc.
+ *  For procs created using <code>Proc.new</code> or <code>Kernel.proc</code>,
+ *  extra parameters are silently discarded and missing parameters are
+ *  set to +nil+.
  *
- *  <em>produces:</em>
+ *     a_proc = proc {|a,b| [a,b] }
+ *     a_proc.call(1)   #=> [1, nil]
  *
- *     prog.rb:4:in `block in <main>': wrong number of arguments (3 for 2) (ArgumentError)
- *     	from prog.rb:5:in `call'
- *     	from prog.rb:5:in `<main>'
+ *     a_proc = lambda {|a,b| [a,b] }
+ *     a_proc.call(1)   # ArgumentError: wrong number of arguments (given 1, expected 2)
  *
+ *  See also Proc#lambda?.
  */
 
 static VALUE
diff --git a/version.h b/version.h
index 03c320c7b2..a3551fa8ac 100644
--- a/version.h
+++ b/version.h
@@ -1,6 +1,6 @@
 #define RUBY_VERSION "2.2.7"
 #define RUBY_RELEASE_DATE "2017-03-26"
-#define RUBY_PATCHLEVEL 437
+#define RUBY_PATCHLEVEL 438
 
 #define RUBY_RELEASE_YEAR 2017
 #define RUBY_RELEASE_MONTH 3