Document behavior when mixing named captures with parentheses [ci skip]

Fixes [Bug #13716]

1 files changed, 9 insertions, 1 deletions

diff --git a/doc/regexp.rdoc b/doc/regexp.rdoc
index 9218a75b67..40c73952d6 100644
--- a/doc/regexp.rdoc
+++ b/doc/regexp.rdoc
@@ -238,7 +238,15 @@ where _name_ is the group name.
         #=> #<MatchData "ototo" vowel:"o">
 
 *Note*: A regexp can't use named backreferences and numbered
-backreferences simultaneously.
+backreferences simultaneously. Also, if a named capture is used in a
+regexp, then parentheses used for grouping which would otherwise result
+in a unnamed capture are treated as non-capturing.
+
+    /(\w)(\w)/.match("ab").captures # => ["a", "b"]
+    /(\w)(\w)/.match("ab").named_captures # => {}
+
+    /(?<c>\w)(\w)/.match("ab").captures # => ["a"]
+    /(?<c>\w)(\w)/.match("ab").named_captures # => {"c"=>"a"}
 
 When named capture groups are used with a literal regexp on the left-hand
 side of an expression and the <tt>=~</tt> operator, the captured text is