[DOC] Tweaks for String#downcase

2 files changed, 15 insertions, 7 deletions

diff --git a/doc/string/downcase.rdoc b/doc/string/downcase.rdoc
index 0fb67daaeb..d5fffa037b 100644
--- a/doc/string/downcase.rdoc
+++ b/doc/string/downcase.rdoc
@@ -1,12 +1,20 @@
 Returns a new string containing the downcased characters in +self+:
 
-   'Hello, World!'.downcase      # => "hello, world!"
-   'ТЕСТ'.downcase               # => "тест"
-   'よろしくお願いします'.downcase # => "よろしくお願いします"
+  'HELLO'.downcase        # => "hello"
+  'STRAẞE'.downcase       # => "straße"
+  'ПРИВЕТ'.downcase       # => "привет"
+  'RubyGems.org'.downcase # => "rubygems.org"
 
-Some characters do not have upcased and downcased versions.
+Some characters (and some character sets) do not have upcase and downcase versions;
+see {Case Mapping}[rdoc-ref:case_mapping.rdoc]:
 
-The casing may be affected by the given +mapping+;
-see {Case Mapping}[rdoc-ref:case_mapping.rdoc].
+  s = '1, 2, 3, ...'
+  s.downcase == s # => true
+  s = 'こんにちは'
+  s.downcase == s # => true
+
+The casing is affected by the given +mapping+,
+which may be +:ascii+, +:fold+, or +:turkic+;
+see {Case Mappings}[rdoc-ref:case_mapping.rdoc@Case+Mappings].
 
 Related: see {Converting to New String}[rdoc-ref:String@Converting+to+New+String].
diff --git a/string.c b/string.c
index de8e37f5d3..ce90c07d15 100644
--- a/string.c
+++ b/string.c
@@ -8052,7 +8052,7 @@ rb_str_downcase_bang(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *    downcase(mapping) -> string
+ *    downcase(mapping = :ascii) -> new_string
  *
  *  :include: doc/string/downcase.rdoc
  *