1 files changed, 17 insertions, 14 deletions
diff --git a/doc/syntax/calling_methods.rdoc b/doc/syntax/calling_methods.rdoc
index b86d60ad88..ea2c49cf31 100644
--- a/doc/syntax/calling_methods.rdoc
+++ b/doc/syntax/calling_methods.rdoc
@@ -98,7 +98,7 @@ to:
 If the method definition has a <code>*argument</code> extra positional
 arguments will be assigned to +argument+ in the method as an Array.
 
-If the method definition doesn't include keyword arguments the keyword or
+If the method definition doesn't include keyword arguments, the keyword or
 hash-type arguments are assigned as a single hash to the last argument:
 
   def my_method(options)
@@ -172,7 +172,8 @@ like positional arguments:
   my_method(positional1, keyword1: value1, keyword2: value2)
 
 Any keyword arguments not given will use the default value from the method
-definition.  If a keyword argument is given that the method did not list an
+definition.  If a keyword argument is given that the method did not list,
+and the method definition does not accept arbitrary keyword arguments, an
 ArgumentError will be raised.
 
 === Block Argument
@@ -285,7 +286,10 @@ If the number of objects in the Array do not match the number of arguments for
 the method, an ArgumentError will be raised.
 
 If the splat operator comes first in the call, parentheses must be used to
-avoid a warning.
+avoid a warning:
+
+  my_method *arguments  # warning
+  my_method(*arguments) # no warning
 
 === Hash to Keyword Arguments Conversion
 
@@ -294,7 +298,8 @@ Given the following method:
   def my_method(first: 1, second: 2, third: 3)
   end
 
-You can turn a Hash into keyword arguments with the <code>**</code> operator:
+You can turn a Hash into keyword arguments with the <code>**</code>
+(keyword splat) operator:
 
   arguments = { first: 3, second: 4, third: 5 }
   my_method(**arguments)
@@ -308,8 +313,9 @@ Both are equivalent to:
 
   my_method(first: 3, second: 4, third: 5)
 
-If the method definition uses <code>**</code> to gather arbitrary keyword
-arguments, they will not be gathered by <code>*</code>:
+If the method definition uses the keyword splat operator to
+gather arbitrary keyword arguments, they will not be gathered
+by <code>*</code>:
 
   def my_method(*a, **kw)
     p arguments: a, keywords: kw
@@ -321,9 +327,6 @@ Prints:
 
   {:arguments=>[1, 2, {"3"=>4}], :keywords=>{:five=>6}}
 
-Unlike the splat operator described above, the <code>**</code> operator has no
-commonly recognized name.
-
 === Proc to Block Conversion
 
 Given a method that use a block:
@@ -333,17 +336,17 @@ Given a method that use a block:
   end
 
 You can convert a proc or lambda to a block argument with the <code>&</code>
-operator:
+(block conversion) operator:
 
   argument = proc { |a| puts "#{a.inspect} was yielded" }
 
   my_method(&argument)
 
-If the splat operator comes first in the call, parenthesis must be used to
-avoid a warning.
+If the block conversion operator comes first in the call, parenthesis must be
+used to avoid a warning:
 
-Unlike the splat operator described above, the <code>&</code> operator has no
-commonly recognized name.
+  my_method &argument  # warning
+  my_method(&argument) # no warning
 
 == Method Lookup