[DOC] Enhanced RDoc for MatchData (#5819)

Treats:
    #begin
    #end
    #match
    #match_length

4 files changed, 107 insertions, 46 deletions

diff --git a/doc/matchdata/begin.rdoc b/doc/matchdata/begin.rdoc
new file mode 100644
index 0000000000..8046dd9d55
--- /dev/null
+++ b/doc/matchdata/begin.rdoc
@@ -0,0 +1,30 @@
+Returns the offset (in characters) of the beginning of the specified match.
+
+When non-negative integer argument +n+ is given,
+returns the offset of the beginning 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.begin(0) # => 1
+  m[3]       # => "113"
+  m.begin(3) # => 3
+
+  m = /(т)(е)(с)/.match('тест')
+  # => #<MatchData "тес" 1:"т" 2:"е" 3:"с">
+  m[0]       # => "тес"
+  m.begin(0) # => 0
+  m[3]       # => "с"
+  m.begin(3) # => 2
+
+When string or symbol argument +name+ is given,
+returns the offset of the beginning for the named match:
+
+  m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
+  # => #<MatchData "hog" foo:"h" bar:"g">
+  m[:foo]        # => "h"
+  m.begin('foo') # => 0
+  m[:bar]        # => "g"
+  m.begin(:bar)  # => 2
+
+Related: MatchData#end, MatchData#offset, MatchData#byteoffset.
diff --git a/doc/matchdata/end.rdoc b/doc/matchdata/end.rdoc
new file mode 100644
index 0000000000..0209b2d2fc
--- /dev/null
+++ b/doc/matchdata/end.rdoc
@@ -0,0 +1,30 @@
+Returns the offset (in characters) of the end of the specified match.
+
+When non-negative integer argument +n+ is given,
+returns the offset of the end 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.end(0) # => 7
+  m[3]     # => "113"
+  m.end(3) # => 6
+
+  m = /(т)(е)(с)/.match('тест')
+  # => #<MatchData "тес" 1:"т" 2:"е" 3:"с">
+  m[0]     # => "тес"
+  m.end(0) # => 3
+  m[3]     # => "с"
+  m.end(3) # => 3
+
+When string or symbol argument +name+ is given,
+returns the offset of the end for the named match:
+
+  m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
+  # => #<MatchData "hog" foo:"h" bar:"g">
+  m[:foo]      # => "h"
+  m.end('foo') # => 1
+  m[:bar]      # => "g"
+  m.end(:bar)  # => 3
+
+Related: MatchData#begin, MatchData#offset, MatchData#byteoffset.
diff --git a/doc/matchdata/offset.rdoc b/doc/matchdata/offset.rdoc
index bbf157548a..0985316d76 100644
--- a/doc/matchdata/offset.rdoc
+++ b/doc/matchdata/offset.rdoc
@@ -29,4 +29,3 @@ returns the starting and ending offsets for the named match:
   m.offset(:bar)  # => [2, 3]
 
 Related: MatchData#byteoffset, MatchData#begin, MatchData#end.
-
diff --git a/re.c b/re.c
index 0b4dfe6446..4b9f2a3849 100644
--- a/re.c
+++ b/re.c
@@ -1287,19 +1287,11 @@ match_byteoffset(VALUE match, VALUE n)
 
 /*
  *  call-seq:
- *     mtch.begin(n)   -> integer
+ *    begin(n) -> integer
+ *    begin(name) -> integer
  *
- *  Returns the offset of the start of the <em>n</em>th element of the match
- *  array in the string.
- *  <em>n</em> can be a string or symbol to reference a named capture.
- *
- *     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
- *     m.begin(0)       #=> 1
- *     m.begin(2)       #=> 2
+ *  :include: doc/matchdata/begin.rdoc
  *
- *     m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
- *     p m.begin(:foo)  #=> 0
- *     p m.begin(:bar)  #=> 2
  */
 
 static VALUE
@@ -1321,19 +1313,11 @@ match_begin(VALUE match, VALUE n)
 
 /*
  *  call-seq:
- *     mtch.end(n)   -> integer
+ *    end(n) -> integer
+ *    end(name) -> integer
  *
- *  Returns the offset of the character immediately following the end of the
- *  <em>n</em>th element of the match array in the string.
- *  <em>n</em> can be a string or symbol to reference a named capture.
- *
- *     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
- *     m.end(0)         #=> 7
- *     m.end(2)         #=> 3
+ *  :include: doc/matchdata/end.rdoc
  *
- *     m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
- *     p m.end(:foo)    #=> 1
- *     p m.end(:bar)    #=> 3
  */
 
 static VALUE
@@ -1354,19 +1338,26 @@ match_end(VALUE match, VALUE n)
 
 /*
  *  call-seq:
- *     mtch.match(n)   -> string or nil
+ *    match(n) -> string or nil
+ *    match(name) -> string or nil
  *
- *  Returns the captured substring corresponding to the argument.
- *  <em>n</em> can be a string or symbol to reference a named capture.
+ *  Returns the matched substring corresponding to the given argument.
+ *
+ *  When non-negative argument +n+ is given,
+ *  returns the matched substring for the <tt>n</tt>th match:
  *
- *     m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.")
- *     m.match(0)       #=> "HX1138"
- *     m.match(4)       #=> "8"
- *     m.match(5)       #=> nil
+ *    m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.")
+ *    # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8" 5:nil>
+ *    m.match(0) # => "HX1138"
+ *    m.match(4) # => "8"
+ *    m.match(5) # => nil
  *
- *     m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
- *     m.match(:foo)    #=> "h"
- *     m.match(:bar)    #=> "ge"
+ *  When string or symbol argument +name+ is given,
+ *  returns the matched substring for the given name:
+ *
+ *    m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
+ *    m.match('foo') # => "h"
+ *    m.match(:bar)  # => "ge"
  *
  */
 
@@ -1387,19 +1378,30 @@ match_nth(VALUE match, VALUE n)
 
 /*
  *  call-seq:
- *     mtch.match_length(n)   -> array
- *
- *  Returns the length of the captured substring corresponding to the argument.
- *  <em>n</em> can be a string or symbol to reference a named capture.
- *
- *     m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.")
- *     m.match_length(0)       #=> 6
- *     m.match_length(4)       #=> 1
- *     m.match_length(5)       #=> nil
- *
- *     m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
- *     m.match_length(:foo)    #=> 1
- *     m.match_length(:bar)    #=> 2
+ *    match_length(n) -> integer or nil
+ *    match_length(name) -> integer or nil
+ *
+ *  Returns the length (in characters) of the matched substring
+ *  corresponding to the given argument.
+ *
+ *  When non-negative argument +n+ is given,
+ *  returns the length of the matched substring
+ *  for the <tt>n</tt>th match:
+ *
+ *    m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.")
+ *    # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8" 5:nil>
+ *    m.match_length(0) # => 6
+ *    m.match_length(4) # => 1
+ *    m.match_length(5) # => nil
+ *
+ *  When string or symbol argument +name+ is given,
+ *  returns the length of the matched substring
+ *  for the named match:
+ *
+ *    m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
+ *    # => #<MatchData "hoge" foo:"h" bar:"ge">
+ *    m.match_length('foo') # => 1
+ *    m.match_length(:bar)  # => 2
  *
  */