diff --git a/string.c b/string.c
index 703797f798..ba4ce86087 100644
--- a/string.c
+++ b/string.c
@@ -3550,35 +3550,41 @@ rb_str_sub_bang(int argc, VALUE *argv, VALUE str)
/*
* call-seq:
* str.sub(pattern, replacement) -> new_str
+ * str.sub(pattern, hash) -> new_str
* str.sub(pattern) {|match| block } -> new_str
- * str.sub(pattern) -> an_enumerator
*
* Returns a copy of str with the first occurrence of
- * pattern replaced with either replacement or the value of the
- * block. The pattern will typically be a Regexp; if it is
- * a String then no regular expression metacharacters will be
- * interpreted (that is /\d/ will match a digit, but
- * '\d' will match a backslash followed by a 'd').
+ * pattern substituted for the second argument. The pattern is
+ * typically a Regexp; if given as a String, any
+ * regular expression metacharacters it contains will be interpreted
+ * literally, e.g. '\\\d' will match a backlash followed by 'd',
+ * instead of a digit.
*
- * If the method call specifies replacement, special variables such as
- * $& will not be useful, as substitution into the string occurs
- * before the pattern match starts. However, the sequences \1,
- * \2, \k, etc., may be used.
+ * If replacement is a String it will be substituted for
+ * the matched text. It may contain back-references to the pattern's capture
+ * groups of the form \\\d, where d is a group number, or
+ * \\\k, where n is a group name. If it is a
+ * double-quoted string, both back-references must be preceded by an
+ * additional backslash. However, within replacement the special match
+ * variables, such as &$, will not refer to the current match.
*
- * In the block form, the current match string is passed in as a parameter, and
- * variables such as $1, $2, $`,
+ * If the second argument is a Hash, and the matched text is one
+ * of its keys, the corresponding value is the replacement string.
+ *
+ * In the block form, the current match string is passed in as a parameter,
+ * and variables such as $1, $2, $`,
* $&, and $' will be set appropriately. The value
* returned by the block will be substituted for the match on each call.
*
- * If no block and no replacement is given, an enumerator is returned instead.
- *
* The result inherits any tainting in the original string or any supplied
* replacement string.
*
* "hello".sub(/[aeiou]/, '*') #=> "h*llo"
* "hello".sub(/([aeiou])/, '<\1>') #=> "hllo"
- * "hello".sub(/./) {|s| s[0].ord.to_s + ' ' } #=> "104 ello"
+ * "hello".sub(/./) {|s| s.ord.to_s + ' ' } #=> "104 ello"
* "hello".sub(/(?[aeiou])/, '*\k*') #=> "h*e*llo"
+ * 'Is SHELL your preferred shell?'.sub(/[[:upper:]]{2,}/, ENV)
+ * #=> "Is /bin/bash your preferred shell?"
*/
static VALUE
@@ -3705,9 +3711,11 @@ str_gsub(int argc, VALUE *argv, VALUE str, int bang)
* call-seq:
* str.gsub!(pattern, replacement) -> str or nil
* str.gsub!(pattern) {|match| block } -> str or nil
+ * str.gsub!(pattern) -> an_enumerator
*
* Performs the substitutions of String#gsub in place, returning
* str, or nil if no substitutions were performed.
+ * If no block and no replacement is given, an enumerator is returned instead.
*/
static VALUE
@@ -3721,34 +3729,44 @@ rb_str_gsub_bang(int argc, VALUE *argv, VALUE str)
/*
* call-seq:
* str.gsub(pattern, replacement) -> new_str
+ * str.gsub(pattern, hash) -> new_str
* str.gsub(pattern) {|match| block } -> new_str
+ * str.gsub(pattern) -> enumerator
*
- * Returns a copy of str with all occurrences of pattern
- * replaced with either replacement or the value of the block. The
- * pattern will typically be a Regexp; if it is a
- * String then no regular expression metacharacters will be
- * interpreted (that is /\d/ will match a digit, but
- * '\d' will match a backslash followed by a 'd').
+ * Returns a copy of str with the all occurrences of
+ * pattern substituted for the second argument. The pattern is
+ * typically a Regexp; if given as a String, any
+ * regular expression metacharacters it contains will be interpreted
+ * literally, e.g. '\\\d' will match a backlash followed by 'd',
+ * instead of a digit.
*
- * If a string is used as the replacement, special variables from the match
- * (such as $& and $1) cannot be substituted into it,
- * as substitution into the string occurs before the pattern match
- * starts. However, the sequences \1, \2,
- * \k, and so on may be used to interpolate
- * successive groups in the match.
+ * If replacement is a String it will be substituted for
+ * the matched text. It may contain back-references to the pattern's capture
+ * groups of the form \\\d, where d is a group number, or
+ * \\\k, where n is a group name. If it is a
+ * double-quoted string, both back-references must be preceded by an
+ * additional backslash. However, within replacement the special match
+ * variables, such as &$, will not refer to the current match.
*
- * In the block form, the current match string is passed in as a parameter, and
- * variables such as $1, $2, $`,
+ * If the second argument is a Hash, and the matched text is one
+ * of its keys, the corresponding value is the replacement string.
+ *
+ * In the block form, the current match string is passed in as a parameter,
+ * and variables such as $1, $2, $`,
* $&, and $' will be set appropriately. The value
* returned by the block will be substituted for the match on each call.
*
* The result inherits any tainting in the original string or any supplied
* replacement string.
*
+ * When neither a block nor a second argument is supplied, an
+ * Enumerator is returned.
+ *
* "hello".gsub(/[aeiou]/, '*') #=> "h*ll*"
* "hello".gsub(/([aeiou])/, '<\1>') #=> "hll"
- * "hello".gsub(/./) {|s| s[0].ord.to_s + ' '} #=> "104 101 108 108 111 "
+ * "hello".gsub(/./) {|s| s.ord.to_s + ' '} #=> "104 101 108 108 111 "
* "hello".gsub(/(?[aeiou])/, '{\k}') #=> "h{e}ll{o}"
+ * 'hello'.gsub(/[eo]/, 'e' => 3, 'o' => '*') #=> "h3ll*"
*/
static VALUE