[pull] master from ruby:master

doc/string/rpartition.rdoc

@@ -1,24 +1,49 @@
 Returns a 3-element array of substrings of +self+.
 
-Matches a pattern against +self+, scanning backwards from the end.
-The pattern is:
+Searches +self+ for a match of +pattern+, seeking the _last_ match.
 
-- +string_or_regexp+ itself, if it is a Regexp.
-- <tt>Regexp.quote(string_or_regexp)</tt>, if +string_or_regexp+ is a string.
+If +pattern+ is not matched, returns the array:
 
-If the pattern is matched, returns pre-match, last-match, post-match:
+  ["", "", self.dup]
 
-  'hello'.rpartition('l')      # => ["hel", "l", "o"]
-  'hello'.rpartition('ll')     # => ["he", "ll", "o"]
-  'hello'.rpartition('h')      # => ["", "h", "ello"]
-  'hello'.rpartition('o')      # => ["hell", "o", ""]
-  'hello'.rpartition(/l+/)     # => ["hel", "l", "o"]
-  'hello'.rpartition('')       # => ["hello", "", ""]
-  'тест'.rpartition('т')       # => ["тес", "т", ""]
-  'こんにちは'.rpartition('に')  # => ["こん", "に", "ちは"]
+If +pattern+ is matched, returns the array:
 
-If the pattern is not matched, returns two empty strings and a copy of +self+:
+  [pre_match, last_match, post_match]
 
-  'hello'.rpartition('x') # => ["", "", "hello"]
+where:
 
-Related: String#partition, String#split.
+- +last_match+ is the last-found matching substring.
+- +pre_match+ and +post_match+ are the preceding and following substrings.
+
+The pattern used is:
+
+- +pattern+ itself, if it is a Regexp.
+- <tt>Regexp.quote(pattern)</tt>, if +pattern+ is a string.
+
+Note that in the examples below, a returned string <tt>'hello'</tt> is a copy of +self+, not +self+.
+
+If +pattern+ is a Regexp, searches for the last matching substring
+(also setting {pattern-matching global variables}[rdoc-ref:globals.md@Pattern+Matching]):
+
+  'hello'.rpartition(/l/)     # => ["hel", "l", "o"]
+  'hello'.rpartition(/ll/)    # => ["he", "ll", "o"]
+  'hello'.rpartition(/h/)     # => ["", "h", "ello"]
+  'hello'.rpartition(/o/)     # => ["hell", "o", ""]
+  'hello'.rpartition(//)      # => ["hello", "", ""]
+  'hello'.rpartition(/x/)     # => ["", "", "hello"]
+  'тест'.rpartition(/т/)      # => ["тес", "т", ""]
+  'こんにちは'.rpartition(/に/) # => ["こん", "に", "ちは"]
+
+If +pattern+ is not a Regexp, converts it to a string (if it is not already one),
+then searches for the last matching substring
+(and does _not_ set {pattern-matching global variables}[rdoc-ref:globals.md@Pattern+Matching]):
+
+  'hello'.rpartition('l')     # => ["hel", "l", "o"]
+  'hello'.rpartition('ll')    # => ["he", "ll", "o"]
+  'hello'.rpartition('h')     # => ["", "h", "ello"]
+  'hello'.rpartition('o')     # => ["hell", "o", ""]
+  'hello'.rpartition('')      # => ["hello", "", ""]
+  'тест'.rpartition('т')      # => ["тес", "т", ""]
+  'こんにちは'.rpartition('に') # => ["こん", "に", "ちは"]
+
+Related: see {Converting to Non-String}[rdoc-ref:String@Converting+to+Non--5CString].

string.c

@@ -10409,10 +10409,12 @@ rstrip_offset(VALUE str, const char *s, const char *e, rb_encoding *enc)
  *  call-seq:
  *    rstrip! -> self or nil
  *
- *  Like String#rstrip, except that any modifications are made in +self+;
- *  returns +self+ if any modification are made, +nil+ otherwise.
+ *  Like String#rstrip, except that:
  *
- *  Related: String#lstrip!, String#strip!.
+ *  - Performs stripping in +self+ (not in a copy of +self+).
+ *  - Returns +self+ if any characters are stripped, +nil+ otherwise.
+ *
+ *  Related: see {Modifying}[rdoc-ref:String@Modifying].
  */
 
 static VALUE
@@ -11194,7 +11196,7 @@ rb_str_partition(VALUE str, VALUE sep)
 
 /*
  *  call-seq:
- *    rpartition(sep) -> [head, match, tail]
+ *    rpartition(pattern) -> [pre_match, last_match, post_match]
  *
  *  :include: doc/string/rpartition.rdoc
  *