Minor updates to methods and calling_methods documentation [ci skip]

2 files changed, 32 insertions, 24 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
 
diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc
index 6424c9d9ec..b3cebe3eaf 100644
--- a/doc/syntax/methods.rdoc
+++ b/doc/syntax/methods.rdoc
@@ -17,8 +17,8 @@ on calling methods}[rdoc-ref:syntax/calling_methods.rdoc].
 == Method Names
 
 Method names may be one of the operators or must start a letter or a character
-with the eight bit set. It may contain letters, numbers, an <code>_</code>
-(underscore or low line) or a character with the eight bit set. The convention
+with the eighth bit set. It may contain letters, numbers, an <code>_</code>
+(underscore or low line) or a character with the eighth bit set. The convention
 is to use underscores to separate words in a multiword method name:
 
   def method_name
@@ -26,7 +26,7 @@ is to use underscores to separate words in a multiword method name:
   end
 
 Ruby programs must be written in a US-ASCII-compatible character set such as
-UTF-8, ISO-8859-1 etc. In such character sets if the eight bit is set it
+UTF-8, ISO-8859-1 etc. In such character sets if the eighth bit is set it
 indicates an extended character. Ruby allows method names and other identifiers
 to contain such characters. Ruby programs cannot contain some characters like
 ASCII NUL (<code>\x00</code>).
@@ -62,9 +62,7 @@ Methods that end with a question mark by convention return boolean, but they
 may not always return just +true+ or +false+.  Often, they will return an
 object to indicate a true value (or "truthy" value).
 
-Methods that end with an equals sign indicate an assignment method.  For
-assignment methods, the return value is ignored and the arguments are returned
-instead.
+Methods that end with an equals sign indicate an assignment method.
 
 These are method names for the various Ruby operators.  Each of these
 operators accepts only one argument.  Following the operator is the typical
@@ -94,8 +92,8 @@ operators.
 <code>></code>   :: greater-than
 <code>>=</code>  :: greater-than or equal
 
-To define unary methods minus, plus, tilde and not (<code>!</code>) follow the
-operator with an <code>@</code> as in <code>+@</code> or <code>!@</code>:
+To define unary methods minus and plus, follow the operator with an
+<code>@</code> as in <code>+@</code>:
 
   class C
     def -@
@@ -107,6 +105,13 @@ operator with an <code>@</code> as in <code>+@</code> or <code>!@</code>:
 
   -obj # prints "you inverted this object"
 
+The <code>@</code> is needed to differentiate unary minus and plus
+operators from binary minus and plus operators.
+
+You can also follow tilde and not (<code>!</code>) unary methods with
+<code>@</code>, but it is not required as there are no binary tilde
+and not operators.
+
 Unary methods accept zero arguments.
 
 Additionally, methods for element reference and assignment may be defined:
@@ -414,8 +419,8 @@ Arbitrary keyword arguments will be accepted with <code>**</code>:
   # 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.
+order.  If an unknown keyword argument is sent by the caller, and the method
+does not accept arbitrary keyword arguments, an ArgumentError is raised.
 
 To require a specific keyword argument, do not include a default value
 for the keyword argument: