NEWS: structured the "Language changes" section

There were too many items in the section in somewhat random order.
This change creates the following five subsections:

* Pattern matching
* The spec of keyword arguments is changed towards 3.0
* Numbered parameter
* proc/lambda without no block is deprecated
* Other miscellaneous changes

Also it adds a handful of example code.

1 files changed, 72 insertions, 11 deletions

diff --git a/NEWS b/NEWS
index a8dc17cbc8..78db0a7637 100644
--- a/NEWS
+++ b/NEWS
@@ -14,10 +14,40 @@ sufficient information, see the ChangeLog file or Redmine
 
 === Language changes
 
+==== Pattern matching
+
 * Pattern matching is introduced as an experimental feature. [Feature #14912]
 
-* Method reference operator, <code>.:</code> is introduced as an
-  experimental feature.  [Feature #12125] [Feature #13581]
+    case [0, [1, 2, 3]]
+    in [a, [b, *c]]
+      p a #=> 0
+      p b #=> 1
+      p c #=> [2, 3]
+    end
+
+    case {a: 0, b: 1}
+    in {a: 0, x: 1}
+      :unreachable
+    in {a: 0, b: var}
+      p var #=> 1
+    end
+
+    json = <<END
+    {
+      "name": "Alice",
+      "age": 30,
+      "children": [{ "name": "Bob", "age": 2 }]
+    }
+    END
+    if JSON.parse(json, symbolize_names: true) in
+         {name: "Alice", children: [{name: "Bob", age: age}]}
+      p age #=> 2
+    end
+
+* See the following slides in detail
+  * https://speakerdeck.com/k_tsj/pattern-matching-new-feature-in-ruby-2-dot-7
+
+==== The spec of keyword arguments is changed towards 3.0
 
 * Automatic conversion of keyword arguments and positional arguments is
   deprecated, and conversion will be removed in Ruby 3.  [Feature #14183]
@@ -64,6 +94,9 @@ sufficient information, see the ChangeLog file or Redmine
 * Non-symbols are allowed as a keyword argument keys if method accepts
   arbitrary keywords. [Feature #14183]
 
+  * Non-Symbol keys in a keyword arguments hash were prohibited in 2.6.0,
+    but are now allowed again.  [Bug #15658]
+
     def foo(**kw); p kw; end; foo("str" => 1) #=> {"str"=>1}
 
 * <code>**nil</code> is allowed in method definitions to explicitly mark
@@ -86,16 +119,31 @@ sufficient information, see the ChangeLog file or Redmine
     h = {}; def foo(*a) a end; foo(h)   # [{}]
     h = {}; def foo(a) a end; foo(h)    # {}
 
+==== Numbered parameter
+
+* Numbered parameter as the default block parameter is introduced as an
+  experimental feature.  [Feature #4475]
+
+    [1, 2, 10].map { _1.to_s(16) } #=> ["1", "2", "a"]
+
+==== proc/lambda without no block is deprecated
+
 * Proc.new and Kernel#proc with no block in a method called with a block is
   warned now.
 
-* Kernel#lambda with no block in a method called with a block errs.
+    def foo
+      proc
+    end
+    foo { puts "Hello" } #=> warning: Capturing the given block using Proc.new is deprecated; use `&block` instead
 
-* Non-Symbol keys in a keyword arguments hash were prohibited in 2.6.0,
-  but are now allowed again.  [Bug #15658]
+* Kernel#lambda with no block in a method called with a block raises an exception.
 
-* Numbered parameter as the default block parameter is introduced as an
-  experimental feature.  [Feature #4475]
+    def bar
+      lambda
+    end
+    bar { puts "Hello" } #=> tried to create Proc object without a block (ArgumentError)
+
+==== Other miscellaneous changes
 
 * A beginless range is experimentally introduced.  It might not be as useful
   as an endless range, but would be good for DSL purpose.  [Feature #14799]
@@ -112,10 +160,9 @@ sufficient information, see the ChangeLog file or Redmine
 * Quoted here-document identifier must end within the same line.
 
      <<"EOS
-     " # This has been warned since 2.4
+     " # This had been warned since 2.4; Now it raises a SyntaxError
      EOS
 
-
 * The flip-flop syntax deprecation is reverted. [Feature #5400]
 
 * Comment lines can be placed between fluent dot now.
@@ -134,6 +181,9 @@ sufficient information, see the ChangeLog file or Redmine
     # Previously parsed as: (a, b = raise) rescue [1, 2]
     # Now parsed as:         a, b = (raise rescue [1, 2])
 
+* Method reference operator, <code>.:</code> is introduced as an
+  experimental feature.  [Feature #12125] [Feature #13581]
+
 === Core classes updates (outstanding ones only)
 
 Array::
@@ -148,6 +198,10 @@ Comparable::
 
     * Comparable#clamp now accepts a Range argument. [Feature #14784]
 
+    -1.clamp(0..2) #=> 0
+     1.clamp(0..2) #=> 1
+     3.clamp(0..2) #=> 2
+
 Complex::
 
   New method::
@@ -163,7 +217,9 @@ Dir::
 
 Encoding::
 
-  * Added new encoding CESU-8 [Feature #15931]
+  New method::
+
+    * Added new encoding CESU-8 [Feature #15931]
 
 Enumerable::
 
@@ -171,8 +227,12 @@ Enumerable::
 
     * Added Enumerable#filter_map.  [Feature #15323]
 
+    [1, 2, 3].filter_map {|x| x.odd? ? x.to_s : nil } #=> ["1", "3"]
+
     * Added Enumerable#tally.  [Feature #11076]
 
+    ["A", "B", "C", "B", "A"].tally #=> {"A"=>2, "B"=>2, "C"=>1}
+
 Enumerator::
 
   New method::
@@ -192,6 +252,7 @@ Fiber::
       exception on the resumed fiber.  [Feature #10344]
 
 File::
+
   Modified method::
 
     * File.extname now returns a dot string at a name ending with a dot on
@@ -311,7 +372,7 @@ Time::
 
 UnboundMethod::
 
-  New methods::
+  New method::
 
     * Added UnboundMethod#bind_call method.  [Feature #15955]