* string.c: Document current situation for String#downcase. [ci skip]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@55215 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

2 files changed, 41 insertions, 4 deletions

diff --git a/ChangeLog b/ChangeLog
index 99ca617e59..1b5d012078 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+Mon May 30 20:00:25 2016  Martin Duerst  <duerst@it.aoyama.ac.jp>
+
+	* string.c: Document current situation for String#downcase. [ci skip]
+
 Mon May 30 18:29:28 2016  Kazuki Yamaguchi  <k@rhe.jp>
 
 	* ext/openssl/ossl_ssl.c (ossl_sslctx_s_alloc): Enable the automatic
diff --git a/string.c b/string.c
index c3fb9b2277..24bcbeecfd 100644
--- a/string.c
+++ b/string.c
@@ -5983,12 +5983,45 @@ rb_str_downcase_bang(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *     str.downcase   -> new_str
+ *     str.downcase              -> new_str
+ *     str.downcase([options])   -> new_str
  *
  *  Returns a copy of <i>str</i> with all uppercase letters replaced with their
- *  lowercase counterparts. The operation is locale insensitive---only
- *  characters ``A'' to ``Z'' are affected.
- *  Note: case replacement is effective only in ASCII region.
+ *  lowercase counterparts. Which letters exactly are replaced, and by which
+ *  other letters, depends on the presence or absence of options, and on the
+ *  +encoding+ of the string.
+ *
+ *  The meaning of the +options+ is as follows:
+ *
+ *  No option ::
+ *    Currently, old behavior (only the ASCII region, i.e. characters
+ *    ``A'' to ``Z'', and/or ``a'' to ``z'', are affected).
+ *    This will change very soon to full Unicode case mapping.
+ *  :ascii ::
+ *    Only the ASCII region, i.e. the characters ``A'' to ``Z'', are affected.
+ *    This option cannot be combined with any other option.
+ *  :turkic ::
+ *    Full Unicode case mapping, adapted for Turkic languages
+ *    (Turkish, Aserbaijani,...). This means that upper case I is mapped to
+ *    lower case dotless i, and so on.
+ *  :lithuanian ::
+ *    Currently, just full Unicode case mapping. In the future, full Unicode
+ *    case mapping adapted for Lithuanian (keeping the dot on the lower case
+ *    i even if there's an accent on top).
+ *  :fold ::
+ *    Only available on +downcase+ and +downcase!+. Unicode case folding, which
+ *    is more far-reaching than Unicode case mapping. This option currently
+ *    cannot be combined with any other option (i.e. we do not currenty
+ *    implement a variant for turkic languages).
+ *
+ *  Please note that several assumptions that are valid for ASCII-only case
+ *  conversions do not hold for more general case conversions. For example,
+ *  the length of the result may not be the same as the length of the input
+ *  (neither in characters nor in bytes), and some roundtrip assumptions
+ *  (e.g. str.downcase == str.downcase.upcase.downcase) may not apply.
+ *
+ *  Non-ASCII case mapping/folding is currently only supported for UTF-8 Strings,
+ *  but this support will be extended to other encodings in the future.
  *
  *     "hEllO".downcase   #=> "hello"
  */