drbrain	2013-01-15 11:49:54 +0900 (Tue, 15 Jan 2013)

  New Revision: 38824

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38824

  Log:
    * doc/syntax/methods.rdoc (Block Argument):  Added section on block
      argument.  Thanks to Andy Lindeman.

  Modified files:
    trunk/ChangeLog
    trunk/doc/syntax/methods.rdoc

Index: doc/syntax/methods.rdoc
===================================================================
--- doc/syntax/methods.rdoc	(revision 38823)
+++ doc/syntax/methods.rdoc	(revision 38824)
@@ -210,6 +210,38 @@ is raised. https://github.com/ruby/ruby/blob/trunk/doc/syntax/methods.rdoc#L210
 When mixing keyword arguments and positional arguments, all positional
 arguments must appear before any keyword arguments.
 
+== Block Argument
+
+The block argument is indicated by <code>&</code> and must come last:
+
+  def my_method(&my_block)
+    my_method.call(self)
+  end
+
+Most frequently the block argument is used to pass a block to another method:
+
+  def each_item(&block)
+    @items.each(&block)
+  end
+
+If you are only going to call the block and will not otherwise manipulate it
+or send it to another method using <code>yield</code> without an explicit
+block parameter is preferred.  This method is equivalent to the first method
+in this section:
+
+  def my_method
+    yield self
+  end
+
+There is also a performance benefit to using yield over a calling a block
+parameter.  When a block argument is assigned to a variable a Proc object is
+created which holds the block.  When using yield this Proc object is not
+created.
+
+If you only need to use the block sometimes you can use Proc.new to create a
+proc from the block that was passed to your method.  See Proc.new for further
+details.
+
 == Exception Handling
 
 Methods have an implied exception handling block so you do not need to use
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 38823)
+++ ChangeLog	(revision 38824)
@@ -1,3 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Tue Jan 15 11:49:31 2013  Eric Hodel  <drbrain@s...>
+
+	* doc/syntax/methods.rdoc (Block Argument):  Added section on block
+	  argument.  Thanks to Andy Lindeman.
+
 Tue Jan 15 10:54:59 2013  Eric Hodel  <drbrain@s...>
 
 	* doc/syntax/calling_methods.rdoc (Arguments):  Added improved

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/