fix doc.

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

21 files changed, 114 insertions, 122 deletions

diff --git a/array.c b/array.c
index bf7777dbfd..7e9dcfa073 100644
--- a/array.c
+++ b/array.c
@@ -1033,7 +1033,7 @@ rb_ary_splice(VALUE ary, long beg, long len, VALUE rpl)
  *     a[0..2] = "A"               #=> ["A", "4"]
  *     a[-1]   = "Z"               #=> ["A", "Z"]
  *     a[1..-1] = nil              #=> ["A", nil]
- *     a[1..-1] = []              #=> ["A"]
+ *     a[1..-1] = []               #=> ["A"]
  */
 
 static VALUE
@@ -3014,13 +3014,14 @@ permute0(long n, long r, long *p, long index, int *used, VALUE values)
  * When invoked without a block, return an enumerator object instead.
  * 
  * Examples:
+ *
  *     a = [1, 2, 3]
  *     a.permutation.to_a     #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
  *     a.permutation(1).to_a  #=> [[1],[2],[3]]
  *     a.permutation(2).to_a  #=> [[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]]
  *     a.permutation(3).to_a  #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
- *     a.permutation(0).to_a  #=> [[]]: one permutation of length 0
- *     a.permutation(4).to_a  #=> []  : no permutations of length 4
+ *     a.permutation(0).to_a  #=> [[]] # one permutation of length 0
+ *     a.permutation(4).to_a  #=> []   # no permutations of length 4
  */
 
 static VALUE
@@ -3094,13 +3095,14 @@ combi_len(long n, long k)
  * When invoked without a block, returns an enumerator object instead.
  *     
  * Examples:
+ *
  *     a = [1, 2, 3, 4]
  *     a.combination(1).to_a  #=> [[1],[2],[3],[4]]
  *     a.combination(2).to_a  #=> [[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]
  *     a.combination(3).to_a  #=> [[1,2,3],[1,2,4],[1,3,4],[2,3,4]]
  *     a.combination(4).to_a  #=> [[1,2,3,4]]
- *     a.combination(0).to_a  #=> [[]]: one combination of length 0
- *     a.combination(5).to_a  #=> []  : no combinations of length 5
+ *     a.combination(0).to_a  #=> [[]] # one combination of length 0
+ *     a.combination(5).to_a  #=> []   # no combinations of length 5
  *     
  */
 
diff --git a/bignum.c b/bignum.c
index 0c31b8c89c..1f38816f6d 100644
--- a/bignum.c
+++ b/bignum.c
@@ -2001,7 +2001,7 @@ bigsqr(VALUE x)
 
 /*
  *  call-seq:
- *     big ** exponent   #=> numeric
+ *     big ** exponent   => numeric
  *
  *  Raises _big_ to the _exponent_ power (which may be an integer, float,
  *  or anything that will coerce to a number). The result may be
diff --git a/class.c b/class.c
index 32a35662bb..60bd2e30be 100644
--- a/class.c
+++ b/class.c
@@ -628,9 +628,9 @@ class_instance_method_list(int argc, VALUE *argv, VALUE mod, int (*func) (ID, lo
  *       def method3()  end
  *     end
  *     
- *     A.instance_methods                #=> ["method1"]
- *     B.instance_methods(false)         #=> ["method2"]
- *     C.instance_methods(false)         #=> ["method3"]
+ *     A.instance_methods                #=> [:method1]
+ *     B.instance_methods(false)         #=> [:method2]
+ *     C.instance_methods(false)         #=> [:method3]
  *     C.instance_methods(true).length   #=> 43
  */
 
@@ -668,8 +668,8 @@ rb_class_protected_instance_methods(int argc, VALUE *argv, VALUE mod)
  *       private :method1
  *       def method2()  end
  *     end
- *     Mod.instance_methods           #=> ["method2"]
- *     Mod.private_instance_methods   #=> ["method1"]
+ *     Mod.instance_methods           #=> [:method2]
+ *     Mod.private_instance_methods   #=> [:method1]
  */
 
 VALUE
@@ -720,9 +720,9 @@ rb_class_public_instance_methods(int argc, VALUE *argv, VALUE mod)
  *       end
  *     end
  *     
- *     Single.singleton_methods    #=> ["four"]
- *     a.singleton_methods(false)  #=> ["two", "one"]
- *     a.singleton_methods         #=> ["two", "one", "three"]
+ *     Single.singleton_methods    #=> [:four]
+ *     a.singleton_methods(false)  #=> [:two, :one]
+ *     a.singleton_methods         #=> [:two, :one, :three]
  */
 
 VALUE
diff --git a/dir.c b/dir.c
index abd20d0fab..d717a8e04b 100644
--- a/dir.c
+++ b/dir.c
@@ -1653,14 +1653,14 @@ dir_s_aref(int argc, VALUE *argv, VALUE obj)
  *
  *     rbfiles = File.join("**", "*.rb")
  *     Dir.glob(rbfiles)                   #=> ["main.rb",
- *                                              "lib/song.rb",
- *                                              "lib/song/karaoke.rb"]
+ *                                         #    "lib/song.rb",
+ *                                         #    "lib/song/karaoke.rb"]
  *     libdirs = File.join("**", "lib")
  *     Dir.glob(libdirs)                   #=> ["lib"]
  *
  *     librbfiles = File.join("**", "lib", "**", "*.rb")
  *     Dir.glob(librbfiles)                #=> ["lib/song.rb",
- *                                              "lib/song/karaoke.rb"]
+ *                                         #    "lib/song/karaoke.rb"]
  *
  *     librbfiles = File.join("**", "lib", "*.rb")
  *     Dir.glob(librbfiles)                #=> ["lib/song.rb"]
@@ -1788,31 +1788,31 @@ dir_entries(VALUE io, VALUE dirname)
  *  parameters. The same glob pattern and flags are used by
  *  <code>Dir::glob</code>.
  *
- *     File.fnmatch('cat',       'cat')        #=> true  : match entire string
- *     File.fnmatch('cat',       'category')   #=> false : only match partial string
- *     File.fnmatch('c{at,ub}s', 'cats')       #=> false : { } isn't supported
+ *     File.fnmatch('cat',       'cat')        #=> true  # match entire string
+ *     File.fnmatch('cat',       'category')   #=> false # only match partial string
+ *     File.fnmatch('c{at,ub}s', 'cats')       #=> false # { } isn't supported
  *
- *     File.fnmatch('c?t',     'cat')          #=> true  : '?' match only 1 character
- *     File.fnmatch('c??t',    'cat')          #=> false : ditto
- *     File.fnmatch('c*',      'cats')         #=> true  : '*' match 0 or more characters
- *     File.fnmatch('c*t',     'c/a/b/t')      #=> true  : ditto
- *     File.fnmatch('ca[a-z]', 'cat')          #=> true  : inclusive bracket expression
- *     File.fnmatch('ca[^t]',  'cat')          #=> false : exclusive bracket expression ('^' or '!')
+ *     File.fnmatch('c?t',     'cat')          #=> true  # '?' match only 1 character
+ *     File.fnmatch('c??t',    'cat')          #=> false # ditto
+ *     File.fnmatch('c*',      'cats')         #=> true  # '*' match 0 or more characters
+ *     File.fnmatch('c*t',     'c/a/b/t')      #=> true  # ditto
+ *     File.fnmatch('ca[a-z]', 'cat')          #=> true  # inclusive bracket expression
+ *     File.fnmatch('ca[^t]',  'cat')          #=> false # exclusive bracket expression ('^' or '!')
  *
- *     File.fnmatch('cat', 'CAT')                     #=> false : case sensitive
- *     File.fnmatch('cat', 'CAT', File::FNM_CASEFOLD) #=> true  : case insensitive
+ *     File.fnmatch('cat', 'CAT')                     #=> false # case sensitive
+ *     File.fnmatch('cat', 'CAT', File::FNM_CASEFOLD) #=> true  # case insensitive
  *
- *     File.fnmatch('?',   '/', File::FNM_PATHNAME)  #=> false : wildcard doesn't match '/' on FNM_PATHNAME
- *     File.fnmatch('*',   '/', File::FNM_PATHNAME)  #=> false : ditto
- *     File.fnmatch('[/]', '/', File::FNM_PATHNAME)  #=> false : ditto
+ *     File.fnmatch('?',   '/', File::FNM_PATHNAME)  #=> false # wildcard doesn't match '/' on FNM_PATHNAME
+ *     File.fnmatch('*',   '/', File::FNM_PATHNAME)  #=> false # ditto
+ *     File.fnmatch('[/]', '/', File::FNM_PATHNAME)  #=> false # ditto
  *
- *     File.fnmatch('\?',   '?')                       #=> true  : escaped wildcard becomes ordinary
- *     File.fnmatch('\a',   'a')                       #=> true  : escaped ordinary remains ordinary
- *     File.fnmatch('\a',   '\a', File::FNM_NOESCAPE)  #=> true  : FNM_NOESACPE makes '\' ordinary
- *     File.fnmatch('[\?]', '?')                       #=> true  : can escape inside bracket expression
+ *     File.fnmatch('\?',   '?')                       #=> true  # escaped wildcard becomes ordinary
+ *     File.fnmatch('\a',   'a')                       #=> true  # escaped ordinary remains ordinary
+ *     File.fnmatch('\a',   '\a', File::FNM_NOESCAPE)  #=> true  # FNM_NOESACPE makes '\' ordinary
+ *     File.fnmatch('[\?]', '?')                       #=> true  # can escape inside bracket expression
  *
- *     File.fnmatch('*',   '.profile')                      #=> false : wildcard doesn't match leading
- *     File.fnmatch('*',   '.profile', File::FNM_DOTMATCH)  #=> true    period by default.
+ *     File.fnmatch('*',   '.profile')                      #=> false # wildcard doesn't match leading
+ *     File.fnmatch('*',   '.profile', File::FNM_DOTMATCH)  #=> true  # period by default.
  *     File.fnmatch('.*',  '.profile')                      #=> true
  *
  *     rbfiles = '**' '/' '*.rb' # you don't have to do like this. just write in single string.
diff --git a/enum.c b/enum.c
index 5e04acbf29..0002cd7280 100644
--- a/enum.c
+++ b/enum.c
@@ -60,9 +60,9 @@ grep_iter_i(VALUE i, VALUE *arg, int argc, VALUE *argv)
  *     
  *     (1..100).grep 38..44   #=> [38, 39, 40, 41, 42, 43, 44]
  *     c = IO.constants
- *     c.grep(/SEEK/)         #=> ["SEEK_END", "SEEK_SET", "SEEK_CUR"]
+ *     c.grep(/SEEK/)         #=> [:SEEK_SET, :SEEK_CUR, :SEEK_END]
  *     res = c.grep(/SEEK/) {|v| IO.const_get(v) }
- *     res                    #=> [2, 0, 1]
+ *     res                    #=> [0, 1, 2]
  *     
  */
 
@@ -646,7 +646,7 @@ sort_by_cmp(const void *ap, const void *bp, void *data)
  *  values in <i>enum</i> through the given block.
  *     
  *     %w{ apple pear fig }.sort_by {|word| word.length}
-                     #=> ["fig", "pear", "apple"]
+ *                   #=> ["fig", "pear", "apple"]
  *     
  *  The current implementation of <code>sort_by</code> generates an
  *  array of tuples containing the original collection element and the
@@ -1294,8 +1294,8 @@ member_i(VALUE item, VALUE *memo)
  *  Returns <code>true</code> if any member of <i>enum</i> equals
  *  <i>obj</i>. Equality is tested using <code>==</code>.
  *     
- *     IO.constants.include? "SEEK_SET"          #=> true
- *     IO.constants.include? "SEEK_NO_FURTHER"   #=> false
+ *     IO.constants.include? :SEEK_SET          #=> true
+ *     IO.constants.include? :SEEK_NO_FURTHER   #=> false
  *     
  */
 
diff --git a/enumerator.c b/enumerator.c
index 02b4f18fb8..9c9dd1848f 100644
--- a/enumerator.c
+++ b/enumerator.c
@@ -88,6 +88,7 @@ enumerator_iter_i(VALUE i, VALUE enum_obj, int argc, VALUE *argv)
  *  Returns Enumerable::Enumerator.new(self, method, *args).
  *
  *  e.g.:
+ *
  *     str = "xyz"
  *
  *     enum = str.enum_for(:each_byte)
diff --git a/error.c b/error.c
index 1a50f6f82b..0901878533 100644
--- a/error.c
+++ b/error.c
@@ -845,7 +845,7 @@ rb_invalid_str(const char *str, const char *type)
  *  The full list of operating system errors on your particular platform
  *  are available as the constants of <code>Errno</code>.
  *
- *     Errno.constants   #=> E2BIG, EACCES, EADDRINUSE, EADDRNOTAVAIL, ...
+ *     Errno.constants   #=> :E2BIG, :EACCES, :EADDRINUSE, :EADDRNOTAVAIL, ...
  */
 
 static st_table *syserr_tbl;
diff --git a/eval.c b/eval.c
index cd65803273..95b3a0371e 100644
--- a/eval.c
+++ b/eval.c
@@ -1979,12 +1979,12 @@ specific_eval(int argc, VALUE *argv, VALUE klass, VALUE self)
  *  parameters supply a filename and starting line number that are used
  *  when reporting compilation errors.
  *
- *     class Klass
+ *     class KlassWithSecret
  *       def initialize
  *         @secret = 99
  *       end
  *     end
- *     k = Klass.new
+ *     k = KlassWithSecret.new
  *     k.instance_eval { @secret }   #=> 99
  */
 
@@ -2011,12 +2011,12 @@ rb_obj_instance_eval(int argc, VALUE *argv, VALUE self)
  *  to _obj_ while the code is executing, giving the code access to
  *  _obj_'s instance variables.  Arguments are passed as block parameters.
  *
- *     class Klass
+ *     class KlassWithSecret
  *       def initialize
  *         @secret = 99
  *       end
  *     end
- *     k = Klass.new
+ *     k = KlassWithSecret.new
  *     k.instance_exec(5) {|x| @secret+x }   #=> 104
  */
 
@@ -2172,7 +2172,7 @@ rb_mod_protected(int argc, VALUE *argv, VALUE module)
  *       def c()  end
  *       private :a
  *     end
- *     Mod.private_instance_methods   #=> ["a", "c"]
+ *     Mod.private_instance_methods   #=> [:a, :c]
  */
 
 static VALUE
diff --git a/hash.c b/hash.c
index 2cb7270304..50fb4d7905 100644
--- a/hash.c
+++ b/hash.c
@@ -538,7 +538,7 @@ rb_hash_fetch(int argc, VALUE *argv, VALUE hash)
  *     h.default(2)                            #=> "cat"
  *
  *     h = Hash.new {|h,k| h[k] = k.to_i*10}   #=> {}
- *     h.default                               #=> 0
+ *     h.default                               #=> nil
  *     h.default(2)                            #=> 20
  */
 
@@ -837,7 +837,7 @@ rb_hash_reject(VALUE hash)
  *
  *   h = { "cat" => "feline", "dog" => "canine", "cow" => "bovine" }
  *   h.values_at("cow", "cat")  #=> ["bovine", "feline"]
-*/
+ */
 
 VALUE
 rb_hash_values_at(int argc, VALUE *argv, VALUE hash)
@@ -1138,7 +1138,7 @@ to_a_i(VALUE key, VALUE value, VALUE ary)
  *  value</i> <code>]</code> arrays.
  *
  *     h = { "c" => 300, "a" => 100, "d" => 400, "c" => 300  }
- *     h.to_a   #=> [["a", 100], ["c", 300], ["d", 400]]
+ *     h.to_a   #=> [["c", 300], ["a", 100], ["d", 400]]
  */
 
 static VALUE
@@ -1195,7 +1195,7 @@ inspect_hash(VALUE hash, VALUE dummy, int recur)
  * Return the contents of this hash as a string.
  *
  *     h = { "c" => 300, "a" => 100, "d" => 400, "c" => 300  }
- *     h.to_s   #=> "{\"a\"=>100, \"c\"=>300, \"d\"=>400}"
+ *     h.to_s   #=> "{\"c\"=>300, \"a\"=>100, \"d\"=>400}"
  */
 
 static VALUE
@@ -1504,7 +1504,7 @@ rb_hash_invert_i(VALUE key, VALUE value, VALUE hash)
  *  the keys as values.
  *
  *     h = { "n" => 100, "m" => 100, "y" => 300, "d" => 200, "a" => 0 }
- *     h.invert   #=> {0=>"a", 100=>"n", 200=>"d", 300=>"y"}
+ *     h.invert   #=> {0=>"a", 100=>"m", 200=>"d", 300=>"y"}
  *
  */
 
@@ -1552,6 +1552,9 @@ rb_hash_update_block_i(VALUE key, VALUE value, VALUE hash)
  *     h1 = { "a" => 100, "b" => 200 }
  *     h2 = { "b" => 254, "c" => 300 }
  *     h1.merge!(h2)   #=> {"a"=>100, "b"=>254, "c"=>300}
+ *
+ *     h1 = { "a" => 100, "b" => 200 }
+ *     h2 = { "b" => 254, "c" => 300 }
  *     h1.merge!(h2) { |key, v1, v2| v1 }
  *                     #=> {"a"=>100, "b"=>200, "c"=>300}
  */
diff --git a/io.c b/io.c
index 8d2f8e088a..1f2af9fb25 100644
--- a/io.c
+++ b/io.c
@@ -2077,9 +2077,9 @@ rb_io_lineno(VALUE io)
  *     $.                         #=> 1
  *     f.lineno = 1000
  *     f.lineno                   #=> 1000
- *     $. # lineno of last read   #=> 1
+ *     $.                         #=> 1         # lineno of last read
  *     f.gets                     #=> "This is line two\n"
- *     $. # lineno of last read   #=> 1001
+ *     $.                         #=> 1001      # lineno of last read
  */
 
 static VALUE
diff --git a/marshal.c b/marshal.c
index 2d54cb8ff5..3242ac622a 100644
--- a/marshal.c
+++ b/marshal.c
@@ -1612,9 +1612,9 @@ marshal_load(int argc, VALUE *argv)
  * first two bytes of marshaled data.
  *
  *     str = Marshal.dump("thing")
- *     RUBY_VERSION   #=> "1.8.0"
- *     str[0]         #=> 4
- *     str[1]         #=> 8
+ *     RUBY_VERSION   #=> "1.9.0"
+ *     str[0].ord     #=> 4
+ *     str[1].ord     #=> 8
  *
  * Some objects cannot be dumped: if the objects to be dumped include
  * bindings, procedure or method objects, instances of class IO, or
diff --git a/numeric.c b/numeric.c
index 3398c37c15..7ac7b0333e 100644
--- a/numeric.c
+++ b/numeric.c
@@ -312,6 +312,7 @@ num_div(VALUE x, VALUE y)
  *
  *
  *  Examples
+ *
  *     11.divmod(3)         #=> [3, 2]
  *     11.divmod(-3)        #=> [-4, -1]
  *     11.divmod(3.5)       #=> [3, 0.5]
diff --git a/object.c b/object.c
index 80bd1673c3..7b364499e2 100644
--- a/object.c
+++ b/object.c
@@ -364,7 +364,7 @@ inspect_obj(VALUE obj, VALUE str, int recur)
  *  generate the string.
  *     
  *     [ 1, 2, 3..4, 'five' ].inspect   #=> "[1, 2, 3..4, \"five\"]"
- *     Time.new.inspect                 #=> "Wed Apr 09 08:54:39 CDT 2003"
+ *     Time.new.inspect                 #=> "2008-03-08 19:43:39 +0900"
  */
 
 
@@ -1074,8 +1074,8 @@ rb_obj_not_match(VALUE obj1, VALUE obj2)
  *       end
  *     end
  *     Mod.class              #=> Module
- *     Mod.constants          #=> ["E", "PI", "CONST"]
- *     Mod.instance_methods   #=> ["meth"]
+ *     Mod.constants          #=> [:CONST, :PI, :E]
+ *     Mod.instance_methods   #=> [:meth]
  *     
  */
 
@@ -1422,9 +1422,10 @@ rb_class_new_instance(int argc, VALUE *argv, VALUE klass)
  *  
  *  Returns the superclass of <i>class</i>, or <code>nil</code>.
  *     
- *     File.superclass     #=> IO
- *     IO.superclass       #=> Object
- *     Object.superclass   #=> nil
+ *     File.superclass          #=> IO
+ *     IO.superclass            #=> Object
+ *     Object.superclass        #=> BasicObject
+ *     BasicObject.superclass   #=> nil
  *     
  */
 
@@ -1509,7 +1510,7 @@ rb_mod_attr_writer(int argc, VALUE *argv, VALUE klass)
  *     module Mod
  *       attr_accessor(:one, :two)
  *     end
- *     Mod.instance_methods.sort   #=> ["one", "one=", "two", "two="]
+ *     Mod.instance_methods.sort   #=> [:one, :one=, :two, :two=]
  */
 
 static VALUE
@@ -1625,8 +1626,8 @@ rb_mod_const_defined(int argc, VALUE *argv, VALUE mod)
  *     end
  *     k = Klass.new
  *     k.methods[0..9]    #=> ["kMethod", "freeze", "nil?", "is_a?", 
- *                             "class", "instance_variable_set",
- *                              "methods", "extend", "__send__", "instance_eval"]
+ *                        #    "class", "instance_variable_set",
+ *                        #    "methods", "extend", "__send__", "instance_eval"]
  *     k.methods.length   #=> 42
  */
 
@@ -2022,7 +2023,7 @@ rb_Integer(VALUE val)
  *     
  *     Integer(123.999)    #=> 123
  *     Integer("0x1a")     #=> 26
- *     Integer(Time.new)   #=> 1049896590
+ *     Integer(Time.new)   #=> 1204973019
  */
 
 static VALUE
diff --git a/proc.c b/proc.c
index 6fafa71a98..bad935d62e 100644
--- a/proc.c
+++ b/proc.c
@@ -709,23 +709,6 @@ proc_to_proc(VALUE self)
     return self;
 }
 
-/*
- *  call-seq:
- *     prc.binding    => binding
- *  
- *  Returns the binding associated with <i>prc</i>. Note that
- *  <code>Kernel#eval</code> accepts either a <code>Proc</code> or a
- *  <code>Binding</code> object as its second parameter.
- *     
- *     def fred(param)
- *       proc {}
- *     end
- *     
- *     b = fred(99)
- *     eval("param", b.binding)   #=> 99
- *     eval("param", b)           #=> 99
- */
-
 static void
 bm_mark(struct METHOD *data)
 {
@@ -1587,7 +1570,6 @@ localjump_reason(VALUE exc)
  *     
  *     b = fred(99)
  *     eval("param", b.binding)   #=> 99
- *     eval("param", b)           #=> 99
  */
 static VALUE
 proc_binding(VALUE self)
diff --git a/process.c b/process.c
index 87db221df3..603b396963 100644
--- a/process.c
+++ b/process.c
@@ -740,11 +740,11 @@ waitall_each(rb_pid_t pid, int status, VALUE ary)
  *     $?.exitstatus                    #=> 99
  *
  *     pid = fork { sleep 3 }           #=> 27440
- *     Time.now                         #=> Wed Apr 09 08:57:09 CDT 2003
+ *     Time.now                         #=> 2008-03-08 19:56:16 +0900
  *     waitpid(pid, Process::WNOHANG)   #=> nil
- *     Time.now                         #=> Wed Apr 09 08:57:09 CDT 2003
+ *     Time.now                         #=> 2008-03-08 19:56:16 +0900
  *     waitpid(pid, 0)                  #=> 27440
- *     Time.now                         #=> Wed Apr 09 08:57:12 CDT 2003
+ *     Time.now                         #=> 2008-03-08 19:56:19 +0900
  */
 
 static VALUE
@@ -1834,11 +1834,11 @@ rb_f_spawn(int argc, VALUE *argv)
  *  thread calls <code>Thread#run</code>. Zero arguments causes +sleep+ to sleep
  *  forever.
  *
- *     Time.new    #=> Wed Apr 09 08:56:32 CDT 2003
+ *     Time.new    #=> 2008-03-08 19:56:19 +0900
  *     sleep 1.2   #=> 1
- *     Time.new    #=> Wed Apr 09 08:56:33 CDT 2003
+ *     Time.new    #=> 2008-03-08 19:56:20 +0900
  *     sleep 1.9   #=> 2
- *     Time.new    #=> Wed Apr 09 08:56:35 CDT 2003
+ *     Time.new    #=> 2008-03-08 19:56:22 +0900
  */
 
 static VALUE
diff --git a/re.c b/re.c
index 34eeaa543c..58f72fbf80 100644
--- a/re.c
+++ b/re.c
@@ -326,7 +326,7 @@ rb_reg_source(VALUE re)
  *
  *      /ab+c/ix.inspect        #=> "/ab+c/ix"
  *
-*/
+ */
 
 static VALUE
 rb_reg_inspect(VALUE re)
@@ -559,7 +559,7 @@ reg_names_iter(const OnigUChar *name, const OnigUChar *name_end,
  *     /(?<foo>.)(?<foo>.)/.names
  *     #=> ["foo"]
  *
- *     /(.)(.)/.names' 
+ *     /(.)(.)/.names
  *     #=> []
  */
 
@@ -600,12 +600,12 @@ reg_named_captures_iter(const OnigUChar *name, const OnigUChar *name_end,
  *    /(?<foo>.)(?<bar>.)/.named_captures
  *    #=> {"foo"=>[1], "bar"=>[2]}
  *
- *    /(?<foo>.)(?<foo>.)/.named_captures'
+ *    /(?<foo>.)(?<foo>.)/.named_captures
  *    #=> {"foo"=>[1, 2]}
  *
  * If there are no named captures, an empty hash is returned.
  *
- *    /(.)(.)/.named_captures' 
+ *    /(.)(.)/.named_captures
  *    #=> {}
  */
 
@@ -1014,16 +1014,16 @@ rb_match_busy(VALUE match)
  *
  *      r = /a/u
  *      r.fixed_encoding?                               #=> true
- *      r.encoding                                      #=> <Encoding:UTF-8>
+ *      r.encoding                                      #=> #<Encoding:UTF-8>
  *      r =~ "\u{6666} a"                               #=> 2
- *      r =~ "\xa1\xa2".force_encoding("euc-jp")        # ArgumentError
+ *      r =~ "\xa1\xa2".force_encoding("euc-jp")        #=> ArgumentError
  *      r =~ "abc".force_encoding("euc-jp")             #=> 0
  *
  *      r = /\u{6666}/
  *      r.fixed_encoding?                               #=> true
- *      r.encoding                                      #=> <Encoding:UTF-8>
+ *      r.encoding                                      #=> #<Encoding:UTF-8>
  *      r =~ "\u{6666} a"                               #=> 0
- *      r =~ "\xa1\xa2".force_encoding("euc-jp")        # ArgumentError
+ *      r =~ "\xa1\xa2".force_encoding("euc-jp")        #=> ArgumentError
  *      r =~ "abc".force_encoding("euc-jp")             #=> nil
  */
 
@@ -3125,7 +3125,7 @@ match_setter(VALUE val)
  *  <em>n</em> can be a string or symbol to reference a named capture.
  *
  *     /c(.)t/ =~ 'cat'        #=> 0
- *     Regexp.last_match       #=> #<MatchData "cat" "a">
+ *     Regexp.last_match       #=> #<MatchData "cat" 1:"a">
  *     Regexp.last_match(0)    #=> "cat"
  *     Regexp.last_match(1)    #=> "a"
  *     Regexp.last_match(2)    #=> nil
diff --git a/sprintf.c b/sprintf.c
index 62c68a12cb..7c488a14ba 100644
--- a/sprintf.c
+++ b/sprintf.c
@@ -325,7 +325,7 @@ sign_bits(int base, const char *p)
  *   # significant digits                          <------->
  *   sprintf("%20.8g", 1234.56789) #=> "           1234.5679"
  *
- *                                             <------->
+ *   #                                         <------->
  *   sprintf("%20.8g", 123456789)  #=> "       1.2345679e+08"
  *
  *   # precision for `s' is
diff --git a/string.c b/string.c
index 7ae755b45c..053db6cbb5 100644
--- a/string.c
+++ b/string.c
@@ -946,8 +946,8 @@ rb_str_times(VALUE str, VALUE times)
  *  the values to be substituted. See <code>Kernel::sprintf</code> for details
  *  of the format string.
  *     
- *     "%05d" % 123                       #=> "00123"
- *     "%-5s: %08x" % [ "ID", self.id ]   #=> "ID   : 200e14d6"
+ *     "%05d" % 123                              #=> "00123"
+ *     "%-5s: %08x" % [ "ID", self.object_id ]   #=> "ID   : 200e14d6"
  */
 
 static VALUE
@@ -2097,6 +2097,7 @@ rb_str_index(VALUE str, VALUE sub, long offset)
  *     "hello".index('e')             #=> 1
  *     "hello".index('lo')            #=> 3
  *     "hello".index('a')             #=> nil
+ *     "hello".index(?e)              #=> 1
  *     "hello".index(101)             #=> 1
  *     "hello".index(/[aeiou]/, -3)   #=> 4
  */
@@ -2206,6 +2207,7 @@ rb_str_rindex(VALUE str, VALUE sub, long pos)
  *     "hello".rindex('e')             #=> 1
  *     "hello".rindex('l')             #=> 3
  *     "hello".rindex('a')             #=> nil
+ *     "hello".rindex(?e)              #=> 1
  *     "hello".rindex(101)             #=> 1
  *     "hello".rindex(/[aeiou]/, -2)   #=> 1
  */
@@ -2276,7 +2278,7 @@ rb_str_rindex_m(int argc, VALUE *argv, VALUE str)
  *  <code>=~</code> in <code>Object</code> returns <code>false</code>.
  *     
  *     "cat o' 9 tails" =~ /\d/   #=> 7
- *     "cat o' 9 tails" =~ 9      #=> false
+ *     "cat o' 9 tails" =~ 9      #=> nil
  */
 
 static VALUE
@@ -2307,7 +2309,7 @@ static VALUE get_pat(VALUE, int);
  *  parameter is present, it specifies the position in the string to begin the
  *  search.
  *     
- *     'hello'.match('(.)\1')      #=> #<MatchData "ll" "l">
+ *     'hello'.match('(.)\1')      #=> #<MatchData "ll" 1:"l">
  *     'hello'.match('(.)\1')[0]   #=> "ll"
  *     'hello'.match(/(.)\1/)[0]   #=> "ll"
  *     'hello'.match('xx')         #=> nil
@@ -3000,7 +3002,7 @@ rb_str_insert(VALUE str, VALUE idx, VALUE str2)
  *  deleted.
  *     
  *     string = "this is a string"
- *     string.slice!(2)        #=> 105
+ *     string.slice!(2)        #=> "i"
  *     string.slice!(3..6)     #=> " is "
  *     string.slice!(/s.*t/)   #=> "sa st"
  *     string.slice!("r")      #=> "r"
@@ -3185,7 +3187,7 @@ rb_str_sub_bang(int argc, VALUE *argv, VALUE str)
  *     
  *     "hello".sub(/[aeiou]/, '*')                  #=> "h*llo"
  *     "hello".sub(/([aeiou])/, '<\1>')             #=> "h<e>llo"
- *     "hello".sub(/./) {|s| s[0].to_s + ' ' }      #=> "104 ello"
+ *     "hello".sub(/./) {|s| s[0].ord.to_s + ' ' }  #=> "104 ello"
  *     "hello".sub(/(?<foo>[aeiou])/, '*\k<foo>*')  #=> "h*e*llo"
  */
 
@@ -3352,7 +3354,7 @@ rb_str_gsub_bang(int argc, VALUE *argv, VALUE str)
  *     
  *     "hello".gsub(/[aeiou]/, '*')                  #=> "h*ll*"
  *     "hello".gsub(/([aeiou])/, '<\1>')             #=> "h<e>ll<o>"
- *     "hello".gsub(/./) {|s| s[0].to_s + ' '}       #=> "104 101 108 108 111 "
+ *     "hello".gsub(/./) {|s| s[0].ord.to_s + ' '}   #=> "104 101 108 108 111 "
  *     "hello".gsub(/(?<foo>[aeiou])/, '{\k<foo>}')  #=> "h{e}ll{o}"
  */
 
@@ -3699,7 +3701,7 @@ prefix_escape(VALUE str, int c, rb_encoding *enc)
  *
  *    str = "hello"
  *    str[3] = "\b"
- *    str.inspect       #=> "\"hel\bo\""
+ *    str.inspect       #=> "\"hel\\bo\""
  */
 
 VALUE
@@ -6230,9 +6232,9 @@ rb_str_is_ascii_only_p(VALUE str)
  *     def Fred()
  *     end
  *     $f3 = :Fred
- *     $f1.id   #=> 2514190
- *     $f2.id   #=> 2514190
- *     $f3.id   #=> 2514190
+ *     $f1.object_id   #=> 2514190
+ *     $f2.object_id   #=> 2514190
+ *     $f3.object_id   #=> 2514190
  *     
  */
 
diff --git a/struct.c b/struct.c
index a8857ffe92..f61854fc22 100644
--- a/struct.c
+++ b/struct.c
@@ -82,7 +82,7 @@ rb_struct_s_members_m(VALUE klass)
  *     
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
- *     joe.members   #=> ["name", "address", "zip"]
+ *     joe.members   #=> [:name, :address, :zip]
  */
 
 static VALUE
@@ -306,11 +306,11 @@ rb_struct_define(const char *name, ...)
  *     
  *     # Create a structure with a name in Struct
  *     Struct.new("Customer", :name, :address)    #=> Struct::Customer
- *     Struct::Customer.new("Dave", "123 Main")   #=> #<Struct::Customer name="Dave", address="123 Main">
+ *     Struct::Customer.new("Dave", "123 Main")   #=> #<struct Struct::Customer name="Dave", address="123 Main">
  *     
  *     # Create a structure named by its constant
  *     Customer = Struct.new(:name, :address)     #=> Customer
- *     Customer.new("Dave", "123 Main")           #=> #<Customer name="Dave", address="123 Main">
+ *     Customer.new("Dave", "123 Main")           #=> #<struct Customer name="Dave", address="123 Main">
  */
 
 static VALUE
diff --git a/time.c b/time.c
index 455f15bc1f..74c6684c7c 100644
--- a/time.c
+++ b/time.c
@@ -1830,7 +1830,7 @@ time_yday(VALUE time)
  *  Returns <code>true</code> if <i>time</i> occurs during Daylight
  *  Saving Time in its time zone.
  *     
- *   CST6CDT:
+ *   # CST6CDT:
  *     Time.local(2000, 1, 1).zone    #=> "CST"
  *     Time.local(2000, 1, 1).isdst   #=> false
  *     Time.local(2000, 1, 1).dst?    #=> false
@@ -1838,7 +1838,7 @@ time_yday(VALUE time)
  *     Time.local(2000, 7, 1).isdst   #=> true
  *     Time.local(2000, 7, 1).dst?    #=> true
  *
- *   Asia/Tokyo:
+ *   # Asia/Tokyo:
  *     Time.local(2000, 1, 1).zone    #=> "JST"
  *     Time.local(2000, 1, 1).isdst   #=> false
  *     Time.local(2000, 1, 1).dst?    #=> false
diff --git a/variable.c b/variable.c
index 6c0ff1b3f5..385831b086 100644
--- a/variable.c
+++ b/variable.c
@@ -707,7 +707,7 @@ gvar_i(ID key, struct global_entry *entry, VALUE ary)
  *  
  *  Returns an array of the names of global variables.
  *     
- *     global_variables.grep /std/   #=> ["$stderr", "$stdout", "$stdin"]
+ *     global_variables.grep /std/   #=> [:$stdin, :$stdout, :$stderr]
  */
 
 VALUE
@@ -1163,7 +1163,7 @@ ivar_i(ID key, VALUE val, VALUE ary)
  *         @iv = 3
  *       end
  *     end
- *     Fred.new.instance_variables   #=> ["@iv"]
+ *     Fred.new.instance_variables   #=> [:@iv]
  */
 
 VALUE
@@ -1868,8 +1868,8 @@ cv_i(ID key, VALUE value, VALUE ary)
  *     class Two < One
  *       @@var2 = 2
  *     end
- *     One.class_variables   #=> ["@@var1"]
- *     Two.class_variables   #=> ["@@var2"]
+ *     One.class_variables   #=> [:@@var1]
+ *     Two.class_variables   #=> [:@@var2]
  */
 
 VALUE