[DOC] Enhanced RDoc for String (#5724)

Treats:

    #scan
    #hex
    #oct
    #crypt
    #ord
    #sum

1 files changed, 57 insertions, 46 deletions

diff --git a/string.c b/string.c
index 84a9d5f9ed..0917f56f35 100644
--- a/string.c
+++ b/string.c
@@ -9958,33 +9958,41 @@ scan_once(VALUE str, VALUE pat, long *start, int set_backref_str)
 
 /*
  *  call-seq:
- *     str.scan(pattern)                         -> array
- *     str.scan(pattern) {|match, ...| block }   -> str
+ *    scan(string_or_regexp) -> array
+ *    scan(string_or_regexp) {|matches| ... } -> self
  *
- *  Both forms iterate through <i>str</i>, matching the pattern (which may be a
- *  Regexp or a String). For each match, a result is
- *  generated and either added to the result array or passed to the block. If
- *  the pattern contains no groups, each individual result consists of the
- *  matched string, <code>$&</code>.  If the pattern contains groups, each
- *  individual result is itself an array containing one entry per group.
+ *  Matches a pattern against +self+; the pattern is:
  *
- *     a = "cruel world"
- *     a.scan(/\w+/)        #=> ["cruel", "world"]
- *     a.scan(/.../)        #=> ["cru", "el ", "wor"]
- *     a.scan(/(...)/)      #=> [["cru"], ["el "], ["wor"]]
- *     a.scan(/(..)(..)/)   #=> [["cr", "ue"], ["l ", "wo"]]
+ *  - +string_or_regexp+ itself, if it is a Regexp.
+ *  - <tt>Regexp.quote(string_or_regexp)</tt>, if +string_or_regexp+ is a string.
  *
- *  And the block form:
+ *  Iterates through +self+, generating a collection of matching results:
  *
- *     a.scan(/\w+/) {|w| print "<<#{w}>> " }
- *     print "\n"
- *     a.scan(/(.)(.)/) {|x,y| print y, x }
- *     print "\n"
+ *  - If the pattern contains no groups, each result is the
+ *    matched string, <code>$&</code>.
+ *  - If the pattern contains groups, each result is an array
+ *    containing one entry per group.
  *
- *  <em>produces:</em>
+ *  With no block given, returns an array of the results:
+ *
+ *    s = 'cruel world'
+ *    s.scan(/\w+/)      # => ["cruel", "world"]
+ *    s.scan(/.../)      # => ["cru", "el ", "wor"]
+ *    s.scan(/(...)/)    # => [["cru"], ["el "], ["wor"]]
+ *    s.scan(/(..)(..)/) # => [["cr", "ue"], ["l ", "wo"]]
+ *
+ *  With a block given, calls the block with each result; returns +self+:
+ *
+ *    s.scan(/\w+/) {|w| print "<<#{w}>> " }
+ *    print "\n"
+ *    s.scan(/(.)(.)/) {|x,y| print y, x }
+ *    print "\n"
+ *
+ *  Output:
  *
  *     <<cruel>> <<world>>
  *     rceu lowlr
+ *
  */
 
 static VALUE
@@ -10023,16 +10031,20 @@ rb_str_scan(VALUE str, VALUE pat)
 
 /*
  *  call-seq:
- *     str.hex   -> integer
+ *    hex -> integer
  *
- *  Treats leading characters from <i>str</i> as a string of hexadecimal digits
+ *  Interprets the leading substring of +self+ as a string of hexadecimal digits
  *  (with an optional sign and an optional <code>0x</code>) and returns the
- *  corresponding number. Zero is returned on error.
+ *  corresponding number;
+ *  returns zero if there is no such leading substring:
+ *
+ *    '0x0a'.hex        # => 10
+ *    '-1234'.hex       # => -4660
+ *    '0'.hex           # => 0
+ *    'non-numeric'.hex # => 0
+ *
+ *  Related: String#oct.
  *
- *     "0x0a".hex     #=> 10
- *     "-1234".hex    #=> -4660
- *     "0".hex        #=> 0
- *     "wombat".hex   #=> 0
  */
 
 static VALUE
@@ -10044,19 +10056,22 @@ rb_str_hex(VALUE str)
 
 /*
  *  call-seq:
- *     str.oct   -> integer
+ *    oct -> integer
+ *
+ *  Interprets the leading substring of +self+ as a string of octal digits
+ *  (with an optional sign) and returns the corresponding number;
+ *  returns zero if there is no such leading substring:
  *
- *  Treats leading characters of <i>str</i> as a string of octal digits (with an
- *  optional sign) and returns the corresponding number.  Returns 0 if the
- *  conversion fails.
+ *    '123'.oct             # => 83
+      '-377'.oct            # => -255
+      '0377non-numeric'.oct # => 255
+      'non-numeric'.oct     # => 0
  *
- *     "123".oct       #=> 83
- *     "-377".oct      #=> -255
- *     "bad".oct       #=> 0
- *     "0377bad".oct   #=> 255
+ *  If +self+ starts with <tt>0</tt>, radix indicators are honored;
+ *  see Kernel#Integer.
+ *
+ *  Related: String#hex.
  *
- *  If +str+ starts with <code>0</code>, radix indicators are honored.
- *  See Kernel#Integer.
  */
 
 static VALUE
@@ -10081,7 +10096,7 @@ crypt_mutex_initialize(void)
 
 /*
  *  call-seq:
- *     str.crypt(salt_str)   -> new_str
+ *    crypt(salt_str) -> new_string
  *
  *  Returns the string generated by calling <code>crypt(3)</code>
  *  standard library function with <code>str</code> and
@@ -10198,11 +10213,10 @@ rb_str_crypt(VALUE str, VALUE salt)
 
 /*
  *  call-seq:
- *     str.ord   -> integer
+ *    ord -> integer
  *
- *  Returns the Integer ordinal of a one-character string.
+ *  :include: doc/string/ord.rdoc
  *
- *     "a".ord         #=> 97
  */
 
 static VALUE
@@ -10215,13 +10229,10 @@ rb_str_ord(VALUE s)
 }
 /*
  *  call-seq:
- *     str.sum(n=16)   -> integer
+ *    sum(n = 16) -> integer
+ *
+ *  :include: doc/string/sum.rdoc
  *
- *  Returns a basic <em>n</em>-bit checksum of the characters in <i>str</i>,
- *  where <em>n</em> is the optional Integer parameter, defaulting
- *  to 16. The result is simply the sum of the binary value of each byte in
- *  <i>str</i> modulo <code>2**n - 1</code>. This is not a particularly good
- *  checksum.
  */
 
 static VALUE