From 9d1dd7a9ed189475730254fbfee52f890759afaf Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Mon, 18 Apr 2022 11:31:30 -0500
Subject: [PATCH] [DOC] Enhanced RDoc for MatchData (#5818)

Treats:
    #regexp
    #names
    #size
    #offset
---
 doc/matchdata/offset.rdoc | 32 ++++++++++++++++++++
 re.c                      | 63 ++++++++++++++++++++-------------------
 2 files changed, 64 insertions(+), 31 deletions(-)
 create mode 100644 doc/matchdata/offset.rdoc

diff --git a/doc/matchdata/offset.rdoc b/doc/matchdata/offset.rdoc
new file mode 100644
index 0000000000..bbf157548a
--- /dev/null
+++ b/doc/matchdata/offset.rdoc
@@ -0,0 +1,32 @@
+Returns a 2-element array containing the beginning and ending
+offsets (in characters) of the specified match.
+
+When non-negative integer argument +n+ is given,
+returns the starting and ending offsets of the <tt>n</tt>th match:
+
+  m = /(.)(.)(\d+)(\d)/.match("THX1138.")
+  # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
+  m[0]        # => "HX1138"
+  m.offset(0) # => [1, 7]
+  m[3]        # => "113"
+  m.offset(3) # => [3, 6]
+
+  m = /(т)(е)(с)/.match('тест')
+  # => #<MatchData "тес" 1:"т" 2:"е" 3:"с">
+  m[0]        # => "тес"
+  m.offset(0) # => [0, 3]
+  m[3]        # => "с"
+  m.offset(3) # => [2, 3]
+
+When string or symbol argument +name+ is given,
+returns the starting and ending offsets for the named match:
+
+  m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
+  # => #<MatchData "hog" foo:"h" bar:"g">
+  m[:foo]         # => "h"
+  m.offset('foo') # => [0, 1]
+  m[:bar]         # => "g"
+  m.offset(:bar)  # => [2, 3]
+
+Related: MatchData#byteoffset, MatchData#begin, MatchData#end.
+
diff --git a/re.c b/re.c
index 5dda7f3b5d..0b4dfe6446 100644
--- a/re.c
+++ b/re.c
@@ -1101,13 +1101,14 @@ match_init_copy(VALUE obj, VALUE orig)
 
 
 /*
- * call-seq:
- *    mtch.regexp   -> regexp
+ *  call-seq:
+ *    regexp -> regexp
  *
- * Returns the regexp.
+ *  Returns the regexp that produced the match:
+ *
+ *    m = /a.*b/.match("abc") # => #<MatchData "ab">
+ *    m.regexp                # => /a.*b/
  *
- *     m = /a.*b/.match("abc")
- *     m.regexp #=> /a.*b/
  */
 
 static VALUE
@@ -1125,17 +1126,24 @@ match_regexp(VALUE match)
 }
 
 /*
- * call-seq:
- *    mtch.names   -> [name1, name2, ...]
+ *  call-seq:
+ *    names -> array_of_names
  *
- * Returns a list of names of captures as an array of strings.
- * This is the same as mtch.regexp.names.
+ *  Returns an array of the capture names
+ *  (see {Named Captures}[rdoc-ref:Regexp@Named+Captures]):
  *
- *     /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge").names
- *     #=> ["foo", "bar", "baz"]
+ *    m = /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge")
+ *    # => #<MatchData "hog" foo:"h" bar:"o" baz:"g">
+ *    m.names # => ["foo", "bar", "baz"]
+ *
+ *    m = /foo/.match('foo') # => #<MatchData "foo">
+ *    m.names # => [] # No named captures.
+ *
+ *  Equivalent to:
+ *
+ *    m = /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge")
+ *    m.regexp.names # => ["foo", "bar", "baz"]
  *
- *     m = /(?<x>.)(?<y>.)?/.match("a") #=> #<MatchData "a" x:"a" y:nil>
- *     m.names                          #=> ["x", "y"]
  */
 
 static VALUE
@@ -1149,14 +1157,16 @@ match_names(VALUE match)
 
 /*
  *  call-seq:
- *     mtch.length   -> integer
- *     mtch.size     -> integer
+ *    size -> integer
  *
- *  Returns the number of elements in the match array.
+ *  Returns size of the match array:
+ *
+ *    m = /(.)(.)(\d+)(\d)/.match("THX1138.")
+ *    # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
+ *    m.size # => 5
+ *
+ *  MatchData#length is an alias for MatchData.size.
  *
- *     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
- *     m.length   #=> 5
- *     m.size     #=> 5
  */
 
 static VALUE
@@ -1218,19 +1228,10 @@ rb_reg_backref_number(VALUE match, VALUE backref)
 
 /*
  *  call-seq:
- *     mtch.offset(n)   -> array
+ *    offset(n) -> [start_offset, end_offset]
+ *    offset(name) -> [start_offset, end_offset]
  *
- *  Returns a two-element array containing the beginning and ending offsets of
- *  the <em>n</em>th match.
- *  <em>n</em> can be a string or symbol to reference a named capture.
- *
- *     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
- *     m.offset(0)      #=> [1, 7]
- *     m.offset(4)      #=> [6, 7]
- *
- *     m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
- *     p m.offset(:foo) #=> [0, 1]
- *     p m.offset(:bar) #=> [2, 3]
+ *  :include: doc/matchdata/offset.rdoc
  *
  */