[DOC] Enhanced RDoc for String (#5753)

Treats:
    #length
    #bytesize

3 files changed, 26 insertions, 12 deletions

diff --git a/doc/string/bytesize.rdoc b/doc/string/bytesize.rdoc
new file mode 100644
index 0000000000..b0567ff67b
--- /dev/null
+++ b/doc/string/bytesize.rdoc
@@ -0,0 +1,11 @@
+Returns the count of bytes (not characters) in +self+:
+
+  'foo'.bytesize        # => 3
+  'тест'.bytesize       # => 8
+  'こんにちは'.bytesize   # => 15
+
+Contrast with String#length:
+
+  'foo'.length       # => 3
+  'тест'.length      # => 4
+  'こんにちは'.length  # => 5
diff --git a/doc/string/length.rdoc b/doc/string/length.rdoc
new file mode 100644
index 0000000000..0a7e17f7dc
--- /dev/null
+++ b/doc/string/length.rdoc
@@ -0,0 +1,13 @@
+Returns the count of characters (not bytes) in +self+:
+
+  'foo'.length        # => 3
+  'тест'.length       # => 4
+  'こんにちは'.length   # => 5
+
+Contrast with String#bytesize:
+
+  'foo'.bytesize        # => 3
+  'тест'.bytesize       # => 8
+  'こんにちは'.bytesize   # => 15
+
+String#size is an alias for String#length.
diff --git a/string.c b/string.c
index f6987459ed..4d5fea2962 100644
--- a/string.c
+++ b/string.c
@@ -2115,14 +2115,8 @@ rb_str_strlen(VALUE str)
  *  call-seq:
  *    length -> integer
  *
- *  Returns the count of characters (not bytes) in +self+:
+ *  :include: doc/string/length.rdoc
  *
- *    "\x80\u3042".length # => 2
- *    "hello".length # => 5
- *
- *  String#size is an alias for String#length.
- *
- *  Related: String#bytesize.
  */
 
 VALUE
@@ -2135,12 +2129,8 @@ rb_str_length(VALUE str)
  *  call-seq:
  *    bytesize -> integer
  *
- *  Returns the count  of bytes in +self+:
- *
- *    "\x80\u3042".bytesize # => 4
- *    "hello".bytesize # => 5
+ *  :include: doc/string/bytesize.rdoc
  *
- *  Related: String#length.
  */
 
 static VALUE