[DOC] Enhanced RDoc for String (#5751)

Adds to doc for String.new, also making it compliant with documentation_guide.rdoc.
    Fixes some broken links in io.c (that I failed to correct yesterday).

doc/string/new.rdoc

@@ -1,36 +1,50 @@
 Returns a new \String that is a copy of +string+.
 
 With no arguments, returns the empty string with the Encoding <tt>ASCII-8BIT</tt>:
+
   s = String.new
   s # => ""
   s.encoding # => #<Encoding:ASCII-8BIT>
 
-With the single \String argument +string+, returns a copy of +string+
-with the same encoding as +string+:
-  s = String.new('Que veut dire ça?')
-  s # => "Que veut dire ça?"
-  s.encoding # => #<Encoding:UTF-8>
+With optional argument +string+ and no keyword arguments,
+returns a copy of +string+ with the same encoding:
 
-Literal strings like <tt>""</tt> or here-documents always use
-{script encoding}[rdoc-ref:Encoding@Script+Encoding], unlike String.new.
+  String.new('foo')               # => "foo"
+  String.new('тест')              # => "тест"
+  String.new('こんにちは')          # => "こんにちは"
 
-With keyword +encoding+, returns a copy of +str+
-with the specified encoding:
-  s = String.new(encoding: 'ASCII')
-  s.encoding # => #<Encoding:US-ASCII>
-  s = String.new('foo', encoding: 'ASCII')
-  s.encoding # => #<Encoding:US-ASCII>
+(Unlike \String.new,
+a {string literal}[rdoc-ref:syntax/literals.rdoc@String+Literals] like <tt>''</tt> or a
+{here document literal}[rdoc-ref:syntax/literals.rdoc@Here+Document+Literals]
+always has {script encoding}[rdoc-ref:encodings.rdoc@Script+Encoding].)
 
-Note that these are equivalent:
-  s0 = String.new('foo', encoding: 'ASCII')
-  s1 = 'foo'.force_encoding('ASCII')
-  s0.encoding == s1.encoding # => true
+With optional keyword argument +encoding+, returns a copy of +string+
+with the specified encoding;
+the +encoding+ may be an Encoding object, an encoding name,
+or an encoding name alias:
 
-With keyword +capacity+, returns a copy of +str+;
-the given +capacity+ may set the size of the internal buffer,
-which may affect performance:
-  String.new(capacity: 1) # => ""
-  String.new(capacity: 4096) # => ""
+  String.new('foo', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII>
+  String.new('foo', encoding: 'US-ASCII').encoding         # => #<Encoding:US-ASCII>
+  String.new('foo', encoding: 'ASCII').encoding            # => #<Encoding:US-ASCII>
+
+The given encoding need not be valid for the string's content,
+and that validity is not checked:
+
+  s = String.new('こんにちは', encoding: 'ascii')
+  s.valid_encoding? # => false
+
+But the given +encoding+ itself is checked:
+
+  String.new('foo', encoding: 'bar') # Raises ArgumentError.
+
+With optional keyword argument +capacity+, returns a copy of +string+
+(or an empty string, if +string+ is not given);
+the given +capacity+ is advisory only,
+and may or may not set the size of the internal buffer,
+which may in turn affect performance:
+
+  String.new(capacity: 1)
+  String.new('foo', capacity: 4096)
 
 The +string+, +encoding+, and +capacity+ arguments may all be used together:
 

doc/transcode.rdoc

@@ -44,7 +44,7 @@ class String
   #   t.encoding                            # => #<Encoding:UTF-8>
   #
   # Optional keyword arguments +enc_opts+ specify encoding options;
-  # see {Encoding Options}[rdoc-ref:Encoding@Encoding+Options].
+  # see {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options].
   def encode(dst_encoding = Encoding.default_internal, **enc_opts)
     # Pseudo code
     Primitive.str_encode(...)

io.c

@@ -7458,7 +7458,7 @@ static VALUE popen_finish(VALUE port, VALUE klass);
  *  Optional keyword arguments +opts+ specify:
  *
  *  - {Open options}[rdoc-ref:IO@Open+Options].
- *  - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
+ *  - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *  - Options for Kernel#spawn.
  *
  *  <b>Forked \Process</b>
@@ -8080,7 +8080,7 @@ rb_freopen(VALUE fname, const char *mode, FILE *fp)
  *  Optional keyword arguments +opts+ specify:
  *
  *  - {Open Options}[rdoc-ref:IO@Open+Options].
- *  - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
+ *  - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *
  */
 
@@ -9012,7 +9012,7 @@ rb_io_make_open_file(VALUE obj)
  *  Optional keyword arguments +opts+ specify:
  *
  *  - {Open Options}[rdoc-ref:IO@Open+Options].
- *  - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
+ *  - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *
  *  Examples:
  *
@@ -9156,7 +9156,7 @@ rb_io_set_encoding_by_bom(VALUE io)
  *  Optional keyword arguments +opts+ specify:
  *
  *  - {Open Options}[rdoc-ref:IO@Open+Options].
- *  - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
+ *  - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *
  *  Examples:
  *
@@ -9835,7 +9835,7 @@ static VALUE argf_readlines(int, VALUE *, VALUE);
  *  For all forms above, optional keyword arguments specify:
  *
  *  - {Line Options}[rdoc-ref:IO@Line+Options].
- *  - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
+ *  - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *
  *  Examples:
  *
@@ -11100,7 +11100,7 @@ pipe_pair_close(VALUE rw)
  *  Optional keyword arguments +opts+ specify:
  *
  *  - {Open Options}[rdoc-ref:IO@Open+Options].
- *  - {Encoding Options}[rdoc-ref:Encoding@Encoding+Options].
+ *  - {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *
  *  With no block given, returns the two endpoints in an array:
  *
@@ -11362,7 +11362,7 @@ io_s_foreach(VALUE v)
  *  Optional keyword arguments +opts+ specify:
  *
  *  - {Open Options}[rdoc-ref:IO@Open+Options].
- *  - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
+ *  - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *  - {Line Options}[rdoc-ref:IO@Line+Options].
  *
  *  Returns an Enumerator if no block is given.
@@ -11460,7 +11460,7 @@ io_s_readlines(VALUE v)
  *  Optional keyword arguments +opts+ specify:
  *
  *  - {Open Options}[rdoc-ref:IO@Open+Options].
- *  - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
+ *  - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *  - {Line Options}[rdoc-ref:IO@Line+Options].
  *
  */
@@ -11550,7 +11550,7 @@ seek_before_access(VALUE argp)
  *  Optional keyword arguments +opts+ specify:
  *
  *  - {Open Options}[rdoc-ref:IO@Open+Options].
- *  - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
+ *  - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *
  */
 
@@ -11741,7 +11741,7 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary)
  *  Optional keyword arguments +opts+ specify:
  *
  *  - {Open Options}[rdoc-ref:IO@Open+Options].
- *  - {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
+ *  - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *
  */
 
@@ -12825,7 +12825,7 @@ rb_io_internal_encoding(VALUE io)
  *  and internal encodings for the stream.
  *
  *  Optional keyword arguments +enc_opts+ specify
- *  {Encoding options}[rdoc-ref:Encoding@Encoding+Options].
+ *  {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].
  *
  */
 

string.c

@@ -1813,9 +1813,7 @@ rb_ec_str_resurrect(struct rb_execution_context_struct *ec, VALUE str)
 /*
  *
  *  call-seq:
- *    String.new(string = '') -> new_string
- *    String.new(string = '', encoding: encoding) -> new_string
- *    String.new(string = '', capacity: size) -> new_string
+ *    String.new(string = '', **opts) -> new_string
  *
  *  :include: doc/string/new.rdoc
  *