[DOC] Enhanced RDoc for MatchData (#5822)

Treats:
    #to_s
    #named_captures
    #string
    #inspect
    #hash
    #==

re.c

@@ -2248,12 +2248,20 @@ match_values_at(int argc, VALUE *argv, VALUE match)
 
 /*
  *  call-seq:
- *     mtch.to_s   -> str
+ *    to_s -> string
  *
- *  Returns the entire matched string.
+ *  Returns the matched string:
  *
  *    m = /(.)(.)(\d+)(\d)/.match("THX1138.")
+ *    # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
  *    m.to_s # => "HX1138"
+ *
+ *    m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
+ *    # => #<MatchData "hoge" foo:"h" bar:"ge">
+ *    m.to_s # => "hoge"
+ *
+ *  Related: MatchData.inspect.
+ *
  */
 
 static VALUE
@@ -2296,25 +2304,27 @@ match_named_captures_iter(const OnigUChar *name, const OnigUChar *name_end,
 
 /*
  *  call-seq:
- *     mtch.named_captures -> hash
+ *    named_captures -> hash
  *
- *  Returns a Hash using named capture.
+ *  Returns a hash of the named captures;
+ *  each key is a capture name; each value is its captured string or +nil+:
  *
- *  A key of the hash is a name of the named captures.
- *  A value of the hash is a string of last successful capture of corresponding
- *  group.
+ *    m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
+ *    # => #<MatchData "hoge" foo:"h" bar:"ge">
+ *    m.named_captures # => {"foo"=>"h", "bar"=>"ge"}
  *
  *    m = /(?<a>.)(?<b>.)/.match("01")
+ *    # => #<MatchData "01" a:"0" b:"1">
  *    m.named_captures #=> {"a" => "0", "b" => "1"}
  *
  *    m = /(?<a>.)(?<b>.)?/.match("0")
+ *    # => #<MatchData "0" a:"0" b:nil>
  *    m.named_captures #=> {"a" => "0", "b" => nil}
  *
  *    m = /(?<a>.)(?<a>.)/.match("01")
+ *    # => #<MatchData "01" a:"0" a:"1">
  *    m.named_captures #=> {"a" => "1"}
  *
- *     m = /(?<a>x)|(?<a>y)/.match("x")
- *     m.named_captures #=> {"a" => "x"}
  */
 
 static VALUE
@@ -2337,12 +2347,15 @@ match_named_captures(VALUE match)
 
 /*
  *  call-seq:
- *     mtch.string   -> str
+ *    string -> string
  *
- *  Returns a frozen copy of the string passed in to <code>match</code>.
+ *  Returns the target string if it was frozen;
+ *  otherwise, returns a frozen copy of the target string:
  *
  *    m = /(.)(.)(\d+)(\d)/.match("THX1138.")
+ *    # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
  *    m.string # => "THX1138."
+ *
  */
 
 static VALUE
@@ -2373,21 +2386,23 @@ match_inspect_name_iter(const OnigUChar *name, const OnigUChar *name_end,
 
 /*
  * call-seq:
- *    mtch.inspect   -> str
+ *   inspect -> string
  *
- * Returns a printable version of <i>mtch</i>.
+ * Returns a string representation of +self+:
  *
- *     puts /.$/.match("foo").inspect
+ *    m = /.$/.match("foo")
  *    # => #<MatchData "o">
+ *    m.inspect # => "#<MatchData \"o\">"
  *
- *     puts /(.)(.)(.)/.match("foo").inspect
+ *    m = /(.)(.)(.)/.match("foo")
  *    # => #<MatchData "foo" 1:"f" 2:"o" 3:"o">
+ *    m.inspect # => "#<MatchData \"foo\" 1:\"f\" 2:\"o\
  *
- *     puts /(.)(.)?(.)/.match("fo").inspect
+ *    m = /(.)(.)?(.)/.match("fo")
  *    # => #<MatchData "fo" 1:"f" 2:nil 3:"o">
+ *    m.inspect # => "#<MatchData \"fo\" 1:\"f\" 2:nil 3:\"o\">"
  *
- *     puts /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge").inspect
- *     #=> #<MatchData "hog" foo:"h" bar:"o" baz:"g">
+ *  Related: MatchData#to_s.
  *
  */
 
@@ -3195,12 +3210,13 @@ rb_reg_equal(VALUE re1, VALUE re2)
 
 /*
  *  call-seq:
- *    mtch.hash   -> integer
+ *    hash -> integer
  *
- * Produce a hash based on the target string, regexp and matched
- * positions of this matchdata.
+ *  Returns the integer hash value for +self+,
+ *  based on the target string, regexp, match, and captures.
  *
  *  See also Object#hash.
+ *
  */
 
 static VALUE
@@ -3222,11 +3238,14 @@ match_hash(VALUE match)
 
 /*
  *  call-seq:
- *    mtch == mtch2   -> true or false
- *    mtch.eql?(mtch2)   -> true or false
+ *    matchdata == object -> true or false
+ *
+ *  Returns +true+ if +object+ is another \MatchData object
+ *  whose target string, regexp, match, and captures
+ *  are the same as +self+, +false+ otherwise.
+ *
+ *  MatchData#eql? is an alias for MatchData#==.
  *
- *  Equality---Two matchdata are equal if their target strings,
- *  patterns, and matched positions are identical.
  */
 
 static VALUE