[DOC] Tweaks for String#swapcase

2 files changed, 21 insertions, 12 deletions

diff --git a/doc/string/swapcase.rdoc b/doc/string/swapcase.rdoc
new file mode 100644
index 0000000000..93859ec823
--- /dev/null
+++ b/doc/string/swapcase.rdoc
@@ -0,0 +1,19 @@
+Returns a string containing the characters in +self+, with cases reversed:
+
+- Each uppercase character is downcased.
+- Each lowercase character is upcased.
+
+Examples:
+
+  'Hello World!'.swapcase # => "hELLO wORLD!"
+  'тест'.swapcase         # => "ТЕСТ"
+
+Some characters (and even character sets) do not have casing:
+
+  '12345'.swapcase    # => "12345"
+  'こんにちは'.swapcase # => "こんにちは"
+
+The casing may be affected by the given +mapping+;
+see {Case Mapping}[rdoc-ref:case_mapping.rdoc].
+
+Related: see {Converting to New String}[rdoc-ref:String@Converting+to+New+String].
diff --git a/string.c b/string.c
index 01af7f6635..fa6ce7f3ec 100644
--- a/string.c
+++ b/string.c
@@ -8232,19 +8232,9 @@ rb_str_swapcase_bang(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *    swapcase(mapping) -> string
+ *    swapcase(mapping) -> new_string
  *
- *  Returns a string containing the characters in +self+, with cases reversed;
- *  each uppercase character is downcased;
- *  each lowercase character is upcased:
- *
- *     s = 'Hello World!' # => "Hello World!"
- *     s.swapcase         # => "hELLO wORLD!"
- *
- *  The casing may be affected by the given +mapping+;
- *  see {Case Mapping}[rdoc-ref:case_mapping.rdoc].
- *
- *  Related: String#swapcase!.
+ *  :include: doc/string/swapcase.rdoc
  *
  */