diff --git a/hash.c b/hash.c
index ed16468e72..91583b44f2 100644
--- a/hash.c
+++ b/hash.c
@@ -3403,20 +3403,18 @@ transform_values_foreach_replace(st_data_t *key, st_data_t *value, st_data_t arg
  *    transform_values {|value| ... } -> new_hash
  *    transform_values -> new_enumerator
  *
- *  Returns a new +Hash+ object; each entry has:
- *  * A key from +self+.
- *  * A value provided by the block.
+ *  With a block given, returns a new hash +new_hash+;
+ *  for each pair +key+/+value+ in +self+,
+ *  calls the block with +value+ and captures its return as +new_value+;
+ *  adds to +new_hash+ the entry +key+/+new_value+:
  *
- *  Transform values:
  *    h = {foo: 0, bar: 1, baz: 2}
  *    h1 = h.transform_values {|value| value * 100}
  *    h1 # => {foo: 0, bar: 100, baz: 200}
  *
- *  Returns a new Enumerator if no block given:
- *    h = {foo: 0, bar: 1, baz: 2}
- *    e = h.transform_values # => #<Enumerator: {foo: 0, bar: 1, baz: 2}:transform_values>
- *    h1 = e.each { |value| value * 100}
- *    h1 # => {foo: 0, bar: 100, baz: 200}
+ *  With no block given, returns a new Enumerator.
+ *
+ *  Related: see {Methods for Transforming Keys and Values}[rdoc-ref:Hash@Methods+for+Transforming+Keys+and+Values].
  */
 static VALUE
 rb_hash_transform_values(VALUE hash)