diff --git a/string.c b/string.c
index 0b3878b9b1..e193539f4f 100644
--- a/string.c
+++ b/string.c
@@ -6092,8 +6092,8 @@ rb_pat_search(VALUE pat, VALUE str, long pos, int set_backref_str)
  *    sub!(pattern, replacement)   -> self or nil
  *    sub!(pattern) {|match| ... } -> self or nil
  *
- *  Returns +self+ with only the first occurrence
- *  (not all occurrences) of the given +pattern+ replaced.
+ *  Replaces the first occurrence (not all occurrences) of the given +pattern+
+ *  on +self+; returns +self+ if a replacement occurred, +nil+ otherwise.
  *
  *  See {Substitution Methods}[rdoc-ref:String@Substitution+Methods].
  *
diff --git a/string.rb b/string.rb
index 1f0e9ceace..941fda0c24 100644
--- a/string.rb
+++ b/string.rb
@@ -29,9 +29,11 @@
 #  These methods perform substitutions:
 #
 #  - String#sub: One substitution (or none); returns a new string.
-#  - String#sub!: One substitution (or none); returns +self+.
+#  - String#sub!: One substitution (or none); returns +self+ if any changes,
+#    +nil+ otherwise.
 #  - String#gsub: Zero or more substitutions; returns a new string.
-#  - String#gsub!: Zero or more substitutions; returns +self+.
+#  - String#gsub!: Zero or more substitutions; returns +self+ if any changes,
+#    +nil+ otherwise.
 #
 #  Each of these methods takes:
 #