string.c: improve docs for String#{concat,<<}

* string.c: [DOC] remove a misleading call-seq for String#concat,
  which suggests that all arguments must be Integers in this case;
  also clarify in the example that the receiver is modified;
  fix grammar for String#<<; move references to the end.

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

string.c

@@ -2944,20 +2944,22 @@ rb_str_concat_literals(size_t num, const VALUE *strary)
 /*
  *  call-seq:
  *     str.concat(obj1, obj2,...)          -> str
- *     str.concat(integer1, integer2,...)  -> str
  *
  *  Concatenates the given object(s) to <i>str</i>. If an object is an
  *  <code>Integer</code>, it is considered a codepoint and converted
  *  to a character before concatenation.
  *
- *  +concat+ can take multiple arguments, and all the arguments are concatenated
+ *  +concat+ can take multiple arguments, and all the arguments are
- *  in order.  See String#<<, which takes a single argument.
+ *  concatenated in order.
  *
  *     a = "hello "
  *     a.concat("world", 33)      #=> "hello world!"
+ *     a                          #=> "hello world!"
  *
  *     b = "sn"
  *     b.concat("_", b, "_", b)   #=> "sn_sn_sn"
+ *
+ *  See also String#<<, which takes a single argument.
  */
 static VALUE
 rb_str_concat_multi(int argc, VALUE *argv, VALUE str)
@@ -2985,15 +2987,15 @@ rb_str_concat_multi(int argc, VALUE *argv, VALUE str)
  *     str << obj      -> str
  *     str << integer  -> str
  *
- *  Append the given object to <i>str</i>. If the object is an
+ *  Appends the given object to <i>str</i>. If the object is an
  *  <code>Integer</code>, it is considered a codepoint and converted
  *  to a character before being appended.
  *
- *  See String#concat, which takes multiple arguments.
- *
  *     a = "hello "
  *     a << "world"   #=> "hello world"
  *     a << 33        #=> "hello world!"
+ *
+ *  See also String#concat, which takes multiple arguments.
  */
 VALUE
 rb_str_concat(VALUE str1, VALUE str2)