Update method definition documentation

* Add endless methods
* Add argument forwarding ...

1 files changed, 86 insertions, 0 deletions

diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc
index 241913cc1a..d5b23bfb33 100644
--- a/doc/syntax/methods.rdoc
+++ b/doc/syntax/methods.rdoc
@@ -11,6 +11,11 @@ A method definition consists of the +def+ keyword, a method name, the body of
 the method, +return+ value and the +end+ keyword.  When called the method will
 execute the body of the method.  This method returns +2+.
 
+Since Ruby 3.0, there is also shorthand syntax for methods consisting of exactly
+one expression:
+
+   def one_plus_one = 1 + 1
+
 This section only covers defining methods.  See also the {syntax documentation
 on calling methods}[rdoc-ref:syntax/calling_methods.rdoc].
 
@@ -64,6 +69,23 @@ object to indicate a true value (or "truthy" value).
 
 Methods that end with an equals sign indicate an assignment method.
 
+  class C
+    def attr
+      @attr
+    end
+
+    def attr=(val)
+      @attr = val
+    end
+  end
+
+  c = C.new
+  c.attr #=> nil
+  c.attr = 10 # calls "attr="
+  c.attr #=> 10
+
+Assignment methods can't be defined with shorthand syntax.
+
 These are method names for the various Ruby operators.  Each of these
 operators accepts only one argument.  Following the operator is the typical
 use or name of the operator.  Creating an alternate meaning for the operator
@@ -258,6 +280,13 @@ The parentheses around the arguments are optional:
     value + 1
   end
 
+The parentheses are mandatory in shorthand method definition:
+
+  # OK
+  def add_one(value) = value + 1
+  # SyntaxError
+  def add_one value = value + 1
+
 Multiple arguments are separated by a comma:
 
   def add_values(a, b)
@@ -563,6 +592,63 @@ in this section:
     yield self
   end
 
+=== Argument forwarding
+
+Since Ruby 2.7, all-arguments forwarding syntax is available:
+
+  def concrete_method(*positional_args, **keyword_args, &block)
+    [positional_args, keyword_args, block]
+  end
+
+  def forwarding_method(...)
+    concrete_method(...)
+  end
+
+  forwarding_method(1, b: 2) { puts 3 }
+  #=>  [[1], {:b=>2}, #<Proc:...skip...>]
+
+Calling with forwarding <code>...</code> available only in methods defined with
+<code>...</code>.
+
+  def regular_method(arg, **kwarg)
+    other_method(...) # Syntax error
+  end
+
+There could be leading arguments before <code>...</code> both in definition and
+in invokation (but in definition they can be only positional arguments without
+default values).
+
+  def request(method, path, **headers)
+    puts "#{method.upcase} #{path} #{headers}"
+  end
+
+  def get(...)
+    request(:GET, ...) # leading argument in invoking
+  end
+
+  get('http://ruby-lang.org', 'Accept' => 'text/html')
+  # Prints: GET http://ruby-lang.org {"Accept"=>"text/html"}
+
+  def logged_get(msg, ...) # leading argument on definition
+    puts "Invoking #get: #{msg}"
+    get(...)
+  end
+
+  logged_get('Ruby site', 'http://ruby-lang.org')
+  # Prints:
+  #   Invoking #get: Ruby site
+  #   GET http://ruby-lang.org {}
+
+Note that omitting parentheses in forwarding calls may lead to unexpected results:
+
+  def log(...)
+    puts ...   # This would be treated as puts()..., e.g. endless range from puts result
+  end
+
+  log("test")
+  # Prints: warning: ... at EOL, should be parenthesized?
+  # ...and then empty line
+
 == Exception Handling
 
 Methods have an implied exception handling block so you do not need to use