[DOC] Use RDoc inclusions in string.c (#5683)

As @peterzhu2118 and @duerst have pointed out, putting string method's RDoc into doc/ (which allows non-ASCII in examples) makes the "click to toggle source" feature not work for that method.

This PR moves the primary method doc back into string.c, then includes RDoc from doc/string/*.rdoc, and also removes doc/string.rdoc.

The affected methods are:

    ::new
    #bytes
    #each_byte
    #each_line
    #split

The call-seq is in string.c because it works there; it did not work when the call-seq is in doc/string/*.rdoc.

This PR also updates the relevant guidance in doc/documentation_guide.rdoc.

Author: BurdetteLamar

doc/documentation_guide.rdoc

@@ -60,34 +60,25 @@ involving new files <tt>doc/*.rdoc</tt>:
     # Documentation for module Bar goes here.
     module Bar; end
 
-- For an instance method Baz#bat (defined in file <tt>baz.c</tt>),
-  create file <tt>doc/baz.rdoc</tt>, declare class +Baz+
-  and instance method +bat+, and place the method documentation above
-  the method declaration:
+- For a method, things are different.
+  Documenting a method as above disables the "click to toggle source" feature
+  in the rendered documentaion.
 
-    # :markup: ruby
-    class Baz
-      # Documentation for method bat goes here.
-      # (Don't forget the call-seq.)
-      def bat; end
-    end
-
-- For a singleton method Bam.bah (defined in file <tt>bam.c</tt>),
-  create file <tt>doc/bam.rdoc</tt>, declare class +Bam+
-  and singleton method +bah+, and place the method documentation above
-  the method declaration:
+  Therefore it's best to use file inclusion:
 
-    # :markup: ruby
-    class Bam
-      # Documentation for method bah goes here.
-      # (Don't forget the call-seq.)
-      def self.bah; end
-    end
+  - Retain the call-seq in the C code.
+  - Use file inclusion (+:include:+) to include text from an .rdoc file.
 
-  See these examples:
+  Example:
 
-  - https://raw.githubusercontent.com/ruby/ruby/master/doc/string.rdoc
-  - https://raw.githubusercontent.com/ruby/ruby/master/doc/transcode.rdoc
+    /*
+     *  call-seq:
+     *    each_byte {|byte| ... } -> self
+     *    each_byte               -> enumerator
+     *
+     *  \:include: doc/string/each_byte.rdoc
+     *
+     */
 
 === \RDoc
 

doc/string.rdoc

@@ -0,0 +1,6 @@
+Returns an array of the bytes in +self+:
+
+  'hello'.bytes # => [104, 101, 108, 108, 111]
+  'тест'.bytes  # => [209, 130, 208, 181, 209, 129, 209, 130]
+  'こんにちは'.bytes
+  # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]

doc/string/bytes.rdoc

@@ -0,0 +1,17 @@
+Calls the given block with each successive byte from +self+;
+returns +self+:
+
+  'hello'.each_byte {|byte| print byte, ' ' }
+  print "\n"
+  'тест'.each_byte {|byte| print byte, ' ' }
+  print "\n"
+  'こんにちは'.each_byte {|byte| print byte, ' ' }
+  print "\n"
+
+Output:
+
+  104 101 108 108 111
+  209 130 208 181 209 129 209 130
+  227 129 147 227 130 147 227 129 171 227 129 161 227 129 175
+
+Returns an enumerator if no block is given.

doc/string/each_byte.rdoc

@@ -0,0 +1,60 @@
+With a block given, forms the substrings ("lines")
+that are the result of splitting +self+
+at each occurrence of the given line separator +line_sep+;
+passes each line to the block;
+returns +self+:
+
+  s = <<~EOT
+  This is the first line.
+  This is line two.
+
+  This is line four.
+  This is line five.
+  EOT
+
+  s.each_line {|line| p line }
+
+Output:
+
+  "This is the first line.\n"
+  "This is line two.\n"
+  "\n"
+  "This is line four.\n"
+  "This is line five.\n"
+
+With a different +line_sep+:
+
+  s.each_line(' is ') {|line| p line }
+
+Output:
+
+  "This is "
+  "the first line.\nThis is "
+  "line two.\n\nThis is "
+  "line four.\nThis is "
+  "line five.\n"
+
+With +chomp+ as +true+, removes the trailing +line_sep+ from each line:
+
+  s.each_line(chomp: true) {|line| p line }
+
+Output:
+
+  "This is the first line."
+  "This is line two."
+  ""
+  "This is line four."
+  "This is line five."
+
+With an empty string as +line_sep+,
+forms and passes "paragraphs" by splitting at each occurrence
+of two or more newlines:
+
+  s.each_line('') {|line| p line }
+
+Output:
+
+  "This is the first line.\nThis is line two.\n\n"
+  "This is line four.\nThis is line five.\n"
+
+With no block given, returns an enumerator.