* doc/syntax/methods.rdoc (Array/Hash Argument): Moved above Keyword

  Arguments
* doc/syntax/methods.rdoc (Keyword Arguments):  Described ** for
  gathering arbitrary keyword arguments.


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

1 files changed, 31 insertions, 17 deletions

diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc
index 832ba269b0..70a916387d 100644
--- a/doc/syntax/methods.rdoc
+++ b/doc/syntax/methods.rdoc
@@ -153,25 +153,10 @@ This will raise a SyntaxError:
     a + b + c
   end
 
-=== Keyword Arguments
-
-Keyword arguments are similar to positional arguments with default values:
-
-  def add_values(first: 1, second: 2)
-    first + second
-  end
-
-When calling a method with keyword arguments the arguments may appear in any
-order.  If an unknown keyword argument is sent by the caller an ArgumentError
-is raised.
-
-When mixing keyword arguments and positional arguments, all positional
-arguments must appear before any keyword arguments.
-
 === Array/Hash Argument
 
-Prefixing an argument with "*" causes any remaining arguments to be converted
-to an Array:
+Prefixing an argument with <code>*</code> causes any remaining arguments to be
+converted to an Array:
 
   def gather_arguments(*arguments)
     p arguments
@@ -196,6 +181,35 @@ However, this only occurs if the method does not declare any keyword arguments.
   gather_arguments_keyword 1, 2, three: 3
   #=> raises: unknown keyword: three (ArgumentError)
 
+Also, note that a bare <code>*</code> can be used to ignore arguments:
+
+  def ignore_arguments(*)
+  end
+
+=== Keyword Arguments
+
+Keyword arguments are similar to positional arguments with default values:
+
+  def add_values(first: 1, second: 2)
+    first + second
+  end
+
+Arbitrary keyword arguments will be accepted with <code>**</code>:
+
+  def gather_arguments(first: nil, **rest)
+    p first, rest
+  end
+
+  gather_arguments first: 1, second: 2, third: 3
+  # prints 1 then {:second=>2, :third=>3}
+
+When calling a method with keyword arguments the arguments may appear in any
+order.  If an unknown keyword argument is sent by the caller an ArgumentError
+is raised.
+
+When mixing keyword arguments and positional arguments, all positional
+arguments must appear before any keyword arguments.
+
 == Exception Handling
 
 Methods have an implied exception handling block so you do not need to use