1 files changed, 11 insertions, 5 deletions
diff --git a/doc/syntax/pattern_matching.rdoc b/doc/syntax/pattern_matching.rdoc
index e49c09a1f8..06aae26d49 100644
--- a/doc/syntax/pattern_matching.rdoc
+++ b/doc/syntax/pattern_matching.rdoc
@@ -221,7 +221,7 @@ For hash patterns, even a simpler form exists: key-only specification (without a
   end
   #=> "matched: 1"
 
-Binding works for nested patterns as well:
+\Binding works for nested patterns as well:
 
   case {name: 'John', friends: [{name: 'Jane'}, {name: 'Rajesh'}]}
   in name:, friends: [{name: first_friend}, *]
@@ -247,17 +247,17 @@ The "rest" part of a pattern also can be bound to a variable:
   else
     "not matched"
   end
-  #=> "matched: 1, {:b=>2, :c=>3}"
+  #=> "matched: 1, {b: 2, c: 3}"
 
-Binding to variables currently does NOT work for alternative patterns joined with <code>|</code>:
+\Binding to variables currently does NOT work for alternative patterns joined with <code>|</code>:
 
   case {a: 1, b: 2}
   in {a: } | Array
+    # ^ SyntaxError (variable capture in alternative pattern)
     "matched: #{a}"
   else
     "not matched"
   end
-  # SyntaxError (illegal variable in alternative pattern (a))
 
 Variables that start with <code>_</code> are the only exclusions from this rule:
 
@@ -422,7 +422,8 @@ These core and library classes implement deconstruction:
 
 == Guard clauses
 
-+if+ can be used to attach an additional condition (guard clause) when the pattern matches. This condition may use bound variables:
++if+ can be used to attach an additional condition (guard clause) when the pattern matches in +case+/+in+ expressions.
+This condition may use bound variables:
 
   case [1, 2]
   in a, b if b == a*2
@@ -450,6 +451,11 @@ These core and library classes implement deconstruction:
   end
   #=> "matched"
 
+Note that <code>=></code> and +in+ operator can not have a guard clause.
+The following examples is parsed as a standalone expression with modifier +if+.
+
+  [1, 2] in a, b if b == a*2
+
 == Appendix A. Pattern syntax
 
 Approximate syntax is: