Add documents

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

1 files changed, 451 insertions, 92 deletions

diff --git a/object.c b/object.c
index afeb1dc3e1..36e616c22d 100644
--- a/object.c
+++ b/object.c
@@ -23,16 +23,23 @@
 #include "id.h"
 #include "probes.h"
 
-VALUE rb_cBasicObject;
-VALUE rb_mKernel;
-VALUE rb_cObject;
-VALUE rb_cModule;
-VALUE rb_cClass;
-VALUE rb_cData;
+/*!
+ * \defgroup object Core objects and their operations
+ * \{
+ */
+
+VALUE rb_cBasicObject; /*!< BasicObject class */
+VALUE rb_mKernel; /*!< Kernel module */
+VALUE rb_cObject; /*!< Object class */
+VALUE rb_cModule; /*!< Module class */
+VALUE rb_cClass; /*!< Class class */
+VALUE rb_cData; /*!< Data class */
 
-VALUE rb_cNilClass;
-VALUE rb_cTrueClass;
-VALUE rb_cFalseClass;
+VALUE rb_cNilClass; /*!< NilClass class */
+VALUE rb_cTrueClass; /*!< TrueClass class */
+VALUE rb_cFalseClass; /*!< FalseClass class */
+
+/*! \cond INTERNAL_MACRO */
 
 #define id_eq               idEq
 #define id_eql              idEqlP
@@ -47,6 +54,20 @@ VALUE rb_cFalseClass;
     (!SPECIAL_CONST_P(obj) && \
      (BUILTIN_TYPE(obj) == T_CLASS || BUILTIN_TYPE(obj) == T_MODULE))
 
+/*! \endcond */
+
+/*!
+ * Make the object invisible from Ruby code.
+ *
+ * It is useful to let Ruby's GC manage your internal data structure --
+ * The object keeps being managed by GC, but \c ObjectSpace#each_objects
+ * never yields the object.
+ *
+ * Note that the object also lose a way to call a method on it.
+ *
+ * \param[in] obj a Ruby object
+ * \sa rb_obj_reveal
+ */
 VALUE
 rb_obj_hide(VALUE obj)
 {
@@ -56,6 +77,14 @@ rb_obj_hide(VALUE obj)
     return obj;
 }
 
+/*!
+ * Make a hidden object visible again.
+ *
+ * It is the caller's responsibility to pass the right \a klass
+ * which \a obj originally used to belong to.
+ *
+ * \sa rb_obj_hide
+ */
 VALUE
 rb_obj_reveal(VALUE obj, VALUE klass)
 {
@@ -65,6 +94,14 @@ rb_obj_reveal(VALUE obj, VALUE klass)
     return obj;
 }
 
+/*!
+ * Fills common (\c RBasic) fields in \a obj.
+ *
+ * \note Prefer rb_newobj_of() to this function.
+ * \param[in,out] obj a Ruby object to be set up.
+ * \param[in] klass \c obj will belong to this class.
+ * \param[in] type one of \c ruby_value_type
+ */
 VALUE
 rb_obj_setup(VALUE obj, VALUE klass, VALUE type)
 {
@@ -73,13 +110,16 @@ rb_obj_setup(VALUE obj, VALUE klass, VALUE type)
     return obj;
 }
 
-/*
+/**
  *  call-seq:
  *     obj === other   -> true or false
  *
  *  Case Equality -- For class Object, effectively the same as calling
  *  <code>#==</code>, but typically overridden by descendants to provide
  *  meaningful semantics in +case+ statements.
+ *--
+ * Same as \c Object#===, case equality.
+ *++
  */
 
 VALUE
@@ -96,6 +136,15 @@ rb_equal(VALUE obj1, VALUE obj2)
     return Qfalse;
 }
 
+/**
+ * Determines if \a obj1 and \a obj2 are equal in terms of
+ * \c Object#eql?.
+ *
+ * \note It actually calls \c #eql? when necessary.
+ *   So you cannot implement \c #eql? with this function.
+ * \retval non-zero if they are eql?
+ * \retval zero if they are not eql?.
+ */
 int
 rb_eql(VALUE obj1, VALUE obj2)
 {
@@ -110,7 +159,7 @@ rb_eql(VALUE obj1, VALUE obj2)
     return Qfalse;
 }
 
-/*
+/**
  *  call-seq:
  *     obj == other        -> true or false
  *     obj.equal?(other)   -> true or false
@@ -144,8 +193,10 @@ rb_eql(VALUE obj1, VALUE obj2)
  *
  *     1 == 1.0     #=> true
  *     1.eql? 1.0   #=> false
+ *--
+ * \private
+ *++
  */
-
 VALUE
 rb_obj_equal(VALUE obj1, VALUE obj2)
 {
@@ -153,45 +204,16 @@ rb_obj_equal(VALUE obj1, VALUE obj2)
     return Qfalse;
 }
 
-#if 0
-/*
- * call-seq:
- *    obj.hash    -> integer
- *
- * Generates an Integer hash value for this object.  This function must have the
- * property that <code>a.eql?(b)</code> implies <code>a.hash == b.hash</code>.
- *
- * The hash value is used along with #eql? by the Hash class to determine if
- * two objects reference the same hash key.  Any hash value that exceeds the
- * capacity of an Integer will be truncated before being used.
- *
- * The hash value for an object may not be identical across invocations or
- * implementations of Ruby.  If you need a stable identifier across Ruby
- * invocations and implementations you will need to generate one with a custom
- * method.
- */
-VALUE
-rb_obj_hash(VALUE obj)
-{
-    VALUE oid = rb_obj_id(obj);
-#if SIZEOF_LONG == SIZEOF_VOIDP
-    st_index_t index = NUM2LONG(oid);
-#elif SIZEOF_LONG_LONG == SIZEOF_VOIDP
-    st_index_t index = NUM2LL(oid);
-#else
-# error not supported
-#endif
-    return LONG2FIX(rb_objid_hash(index));
-}
-#else
 VALUE rb_obj_hash(VALUE obj);
-#endif
 
-/*
+/**
  *  call-seq:
  *     !obj    -> true or false
  *
  *  Boolean negate.
+ *--
+ * \private
+ *++
  */
 
 VALUE
@@ -200,11 +222,14 @@ rb_obj_not(VALUE obj)
     return RTEST(obj) ? Qfalse : Qtrue;
 }
 
-/*
+/**
  *  call-seq:
  *     obj != other        -> true or false
  *
  *  Returns true if two objects are not-equal, otherwise false.
+ *--
+ * \private
+ *++
  */
 
 VALUE
@@ -214,6 +239,14 @@ rb_obj_not_equal(VALUE obj1, VALUE obj2)
     return RTEST(result) ? Qfalse : Qtrue;
 }
 
+/*!
+ * Looks up the nearest ancestor of \a cl, skipping singleton classes or
+ * module inclusions.
+ * It returns the \a cl itself if it is neither a singleton class or a module.
+ *
+ * \param[in] cl a Class object.
+ * \return the ancestor class found, or a falsthy vaule if nothing found.
+ */
 VALUE
 rb_class_real(VALUE cl)
 {
@@ -224,7 +257,7 @@ rb_class_real(VALUE cl)
     return cl;
 }
 
-/*
+/**
  *  call-seq:
  *     obj.class    -> class
  *
@@ -234,8 +267,12 @@ rb_class_real(VALUE cl)
  *
  *     1.class      #=> Integer
  *     self.class   #=> Object
+ *--
+ * Equivalent to \c Object\#class in Ruby.
+ *
+ * Returns the class of \c obj, skipping singleton classes or module inclusions.
+ *++
  */
-
 VALUE
 rb_obj_class(VALUE obj)
 {
@@ -265,6 +302,7 @@ rb_obj_singleton_class(VALUE obj)
     return rb_singleton_class(obj);
 }
 
+/*! \private */
 void
 rb_obj_copy_ivar(VALUE dest, VALUE obj)
 {
@@ -311,7 +349,7 @@ init_copy(VALUE dest, VALUE obj)
 static int freeze_opt(int argc, VALUE *argv);
 static VALUE immutable_obj_clone(VALUE obj, int kwfreeze);
 static VALUE mutable_obj_clone(VALUE obj, int kwfreeze);
-PUREFUNC(static inline int special_object_p(VALUE obj));
+PUREFUNC(static inline int special_object_p(VALUE obj)); /*!< \private */
 static inline int
 special_object_p(VALUE obj)
 {
@@ -363,6 +401,7 @@ rb_obj_clone2(int argc, VALUE *argv, VALUE obj)
     return immutable_obj_clone(obj, kwfreeze);
 }
 
+/*! \private */
 VALUE
 rb_immutable_obj_clone(int argc, VALUE *argv, VALUE obj)
 {
@@ -426,6 +465,12 @@ mutable_obj_clone(VALUE obj, int kwfreeze)
     return clone;
 }
 
+/**
+ * :nodoc
+ *--
+ * Almost same as \c Object#clone
+ *++
+ */
 VALUE
 rb_obj_clone(VALUE obj)
 {
@@ -433,7 +478,7 @@ rb_obj_clone(VALUE obj)
     return mutable_obj_clone(obj, Qtrue);
 }
 
-/*
+/**
  *  call-seq:
  *     obj.dup -> an_object
  *
@@ -473,9 +518,10 @@ rb_obj_clone(VALUE obj)
  *
  *	s3 = s1.dup #=> #<Klass:0x401b3a38>
  *	s3.foo #=> NoMethodError: undefined method `foo' for #<Klass:0x401b3a38>
- *
+ *--
+ * Equivalent to \c Object\#dup in Ruby
+ *++
  */
-
 VALUE
 rb_obj_dup(VALUE obj)
 {
@@ -532,7 +578,14 @@ rb_obj_yield_self(VALUE obj)
     return rb_yield_values2(1, &obj);
 }
 
-/* :nodoc: */
+/**
+ * :nodoc:
+ *--
+ * Default implemenentation of \c #initialize_copy
+ * \param[in,out] obj the receiver being initialized
+ * \param[in] orig    the object to be copied from.
+ *++
+ */
 VALUE
 rb_obj_init_copy(VALUE obj, VALUE orig)
 {
@@ -545,7 +598,15 @@ rb_obj_init_copy(VALUE obj, VALUE orig)
     return obj;
 }
 
-/* :nodoc: */
+/*!
+ * :nodoc:
+ *--
+ * Default implementation of \c #initialize_dup and \c #initialize_clone
+ *
+ * \param[in,out] obj the receiver being initialized
+ * \param[in] orig    the object to be dup or cloned from.
+ *++
+ **/
 VALUE
 rb_obj_init_dup_clone(VALUE obj, VALUE orig)
 {
@@ -553,7 +614,7 @@ rb_obj_init_dup_clone(VALUE obj, VALUE orig)
     return obj;
 }
 
-/*
+/**
  *  call-seq:
  *     obj.to_s    -> string
  *
@@ -561,8 +622,11 @@ rb_obj_init_dup_clone(VALUE obj, VALUE orig)
  *  <code>to_s</code> prints the object's class and an encoding of the
  *  object id. As a special case, the top-level object that is the
  *  initial execution context of Ruby programs returns ``main''.
+ *
+ *--
+ * Default implementation of \c #to_s.
+ *++
  */
-
 VALUE
 rb_any_to_s(VALUE obj)
 {
@@ -576,7 +640,13 @@ rb_any_to_s(VALUE obj)
 }
 
 VALUE rb_str_escape(VALUE str);
-/*
+/*!
+ * Convenient wrapper of \c Object#inspect.
+ * Returns a human-readable strng representation of \a obj,
+ * similarly to \c Object#inspect.
+ *
+ * Unlike Ruby-level \c #inspect, it escapes characters to keep the
+ * result compatible to the default internal or external encoding.
  * If the default internal or external encoding is ASCII compatible,
  * the encoding of the inspected result must be compatible with it.
  * If the default internal or external encoding is ASCII incompatible,
@@ -586,6 +656,7 @@ VALUE
 rb_inspect(VALUE obj)
 {
     VALUE str = rb_obj_as_string(rb_funcallv(obj, id_inspect, 0, 0));
+
     rb_encoding *enc = rb_default_internal_encoding();
     if (enc == NULL) enc = rb_default_external_encoding();
     if (!rb_enc_asciicompat(enc)) {
@@ -699,7 +770,7 @@ class_or_module_required(VALUE c)
 
 static VALUE class_search_ancestor(VALUE cl, VALUE c);
 
-/*
+/**
  *  call-seq:
  *     obj.instance_of?(class)    -> true or false
  *
@@ -714,6 +785,13 @@ static VALUE class_search_ancestor(VALUE cl, VALUE c);
  *     b.instance_of? A   #=> false
  *     b.instance_of? B   #=> true
  *     b.instance_of? C   #=> false
+ *--
+ * Determines if \a obj is an instance of \a c.
+ *
+ * Equivalent to \c Object\#is_instance_of in Ruby. 
+ * \param[in] obj the object to be determined.
+ * \param[in] c a Class object
+ *++
  */
 
 VALUE
@@ -725,7 +803,7 @@ rb_obj_is_instance_of(VALUE obj, VALUE c)
 }
 
 
-/*
+/**
  *  call-seq:
  *     obj.is_a?(class)       -> true or false
  *     obj.kind_of?(class)    -> true or false
@@ -751,6 +829,13 @@ rb_obj_is_instance_of(VALUE obj, VALUE c)
  *     b.kind_of? B       #=> true
  *     b.kind_of? C       #=> false
  *     b.kind_of? M       #=> true
+ *--
+ * Determines if \a obj is a kind of \a c.
+ *
+ * Equivalent to \c Object\#kind_of? in Ruby.
+ * \param[in] obj the object to be determined
+ * \param[in] c a Module object.
+ *++
  */
 
 VALUE
@@ -773,6 +858,7 @@ class_search_ancestor(VALUE cl, VALUE c)
     return 0;
 }
 
+/*! \private */
 VALUE
 rb_class_search_ancestor(VALUE cl, VALUE c)
 {
@@ -781,7 +867,7 @@ rb_class_search_ancestor(VALUE cl, VALUE c)
     return class_search_ancestor(cl, RCLASS_ORIGIN(c));
 }
 
-/*
+/**
  *  call-seq:
  *     obj.tap {|x| block }    -> obj
  *
@@ -794,6 +880,9 @@ rb_class_search_ancestor(VALUE cl, VALUE c)
  *       .select {|x| x.even? } .tap {|x| puts "evens:    #{x}" }
  *       .map {|x| x*x }        .tap {|x| puts "squares:  #{x}" }
  *
+ *--
+ * \private
+ *++
  */
 
 VALUE
@@ -1037,13 +1126,21 @@ rb_obj_dummy(void)
     return Qnil;
 }
 
-/*
+/**
  *  call-seq:
  *     obj.tainted?    -> true or false
  *
  *  Returns true if the object is tainted.
  *
  *  See #taint for more information.
+ *--
+ * Determines if \a obj is tainted. Equivalent to \c Object\#tainted? in Ruby.
+ * \param[in] obj  the object to be determined
+ * \retval Qtrue if the object is tainted
+ * \retval Qfalse if the object is not tainted
+ * \sa rb_obj_taint
+ * \sa rb_obj_untaint
+ *++
  */
 
 VALUE
@@ -1054,7 +1151,7 @@ rb_obj_tainted(VALUE obj)
     return Qfalse;
 }
 
-/*
+/**
  *  call-seq:
  *     obj.taint -> obj
  *
@@ -1069,6 +1166,13 @@ rb_obj_tainted(VALUE obj)
  *
  *  You should only untaint a tainted object if your code has inspected it and
  *  determined that it is safe. To do so use #untaint.
+ *--
+ * Marks the object as tainted. Equivalent to \c Object\#taint in Ruby
+ * \param[in] obj  the object to be tainted
+ * \return the object itself
+ * \sa rb_obj_untaint
+ * \sa rb_obj_tainted
+ *++
  */
 
 VALUE
@@ -1082,13 +1186,22 @@ rb_obj_taint(VALUE obj)
 }
 
 
-/*
+/**
  *  call-seq:
  *     obj.untaint    -> obj
  *
  *  Removes the tainted mark from the object.
  *
  *  See #taint for more information.
+ *--
+ * Removes the tainted mark from the object.
+ * Equivalent to \c Object\#untaint in Ruby.
+ *
+ * \param[in] obj  the object to be tainted
+ * \return the object itself
+ * \sa rb_obj_taint
+ * \sa rb_obj_tainted
+ *++
  */
 
 VALUE
@@ -1101,11 +1214,20 @@ rb_obj_untaint(VALUE obj)
     return obj;
 }
 
-/*
+/**
  *  call-seq:
  *     obj.untrusted?    -> true or false
  *
  *  Deprecated method that is equivalent to #tainted?.
+ *--
+ * \deprecated Use rb_obj_tainted.
+ *
+ * Trustiness used to have independent semantics from taintedness.
+ * But now trustiness of objects is obsolete and this function behaves
+ * the same as rb_obj_tainted.
+ *
+ * \sa rb_obj_tainted
+ *++
  */
 
 VALUE
@@ -1115,11 +1237,20 @@ rb_obj_untrusted(VALUE obj)
     return rb_obj_tainted(obj);
 }
 
-/*
+/**
  *  call-seq:
  *     obj.untrust -> obj
  *
  *  Deprecated method that is equivalent to #taint.
+ *--
+ * \deprecated Use rb_obj_taint(obj)
+ *
+ * Trustiness used to have independent semantics from taintedness.
+ * But now trustiness of objects is obsolete and this function behaves
+ * the same as rb_obj_taint.
+ *
+ * \sa rb_obj_taint
+ *++
  */
 
 VALUE
@@ -1130,11 +1261,20 @@ rb_obj_untrust(VALUE obj)
 }
 
 
-/*
+/**
  *  call-seq:
  *     obj.trust    -> obj
  *
  *  Deprecated method that is equivalent to #untaint.
+ *--
+ * \deprecated Use rb_obj_untaint(obj)
+ *
+ * Trustiness used to have independent semantics from taintedness.
+ * But now trustiness of objects is obsolete and this function behaves
+ * the same as rb_obj_untaint.
+ *
+ * \sa rb_obj_untaint
+ *++
  */
 
 VALUE
@@ -1144,13 +1284,21 @@ rb_obj_trust(VALUE obj)
     return rb_obj_untaint(obj);
 }
 
+/**
+ * Convenient function to infect \a victim with the taintedness of \a carrier.
+ *
+ * It just keeps the taintedness of \a victim if \a carrier is not tainted.
+ * \param[in,out] victim the object being infected with the taintness of \a carrier
+ * \param[in] carrier a possibly tainted object
+ */
+
 void
-rb_obj_infect(VALUE obj1, VALUE obj2)
+rb_obj_infect(VALUE victim, VALUE carrier)
 {
-    OBJ_INFECT(obj1, obj2);
+    OBJ_INFECT(victim, carrier);
 }
 
-/*
+/**
  *  call-seq:
  *     obj.freeze    -> obj
  *
@@ -1172,6 +1320,11 @@ rb_obj_infect(VALUE obj1, VALUE obj2)
  *
  *  Objects of the following classes are always frozen: Integer,
  *  Float, Symbol.
+ *--
+ * Make the object unmodifiable. Equivalent to \c Object\#freeze in Ruby.
+ * \param[in,out] obj  the object to be frozen
+ * \return the frozen object
+ *++
  */
 
 VALUE
@@ -1186,7 +1339,7 @@ rb_obj_freeze(VALUE obj)
     return obj;
 }
 
-/*
+/**
  *  call-seq:
  *     obj.frozen?    -> true or false
  *
@@ -1195,6 +1348,12 @@ rb_obj_freeze(VALUE obj)
  *     a = [ "a", "b", "c" ]
  *     a.freeze    #=> ["a", "b", "c"]
  *     a.frozen?   #=> true
+ *--
+ * Determines if the object is frozen. Equivalent to \c Object\#frozen? in Ruby.
+ * \param[in] obj  the object to be determines
+ * \retval Qtrue if frozen
+ * \retval Qfalse if not frozen
+ *++
  */
 
 VALUE
@@ -1644,7 +1803,7 @@ rb_mod_eqq(VALUE mod, VALUE arg)
     return rb_obj_is_kind_of(arg, mod);
 }
 
-/*
+/**
  * call-seq:
  *   mod <= other   ->  true, false, or nil
  *
@@ -1653,7 +1812,15 @@ rb_mod_eqq(VALUE mod, VALUE arg)
  * <code>nil</code> if there's no relationship between the two.
  * (Think of the relationship in terms of the class definition:
  * "class A < B" implies "A < B".)
- *
+ *--
+ * Determines if \a mod inherits \a arg. Equivalent to \c Module\#<= in Ruby
+ *
+ * \param[in] mod a Module object
+ * \param[in] arg another Module object or an iclass of a module
+ * \retval Qtrue if \a mod inherits \a arg
+ * \retval Qfalse if \a arg inherits \a mod
+ * \retval Qnil if otherwise
+ *++
  */
 
 VALUE
@@ -1879,6 +2046,7 @@ rb_class_initialize(int argc, VALUE *argv, VALUE klass)
     return klass;
 }
 
+/*! \private */
 void
 rb_undefined_alloc(VALUE klass)
 {
@@ -1935,6 +2103,20 @@ rb_class_alloc(VALUE klass)
     return obj;
 }
 
+/**
+ * Allocates an instance of \a klass
+ *
+ * \note It calls the allocator defined by {rb_define_alloc_func}.
+ *   So you cannot use this function to define an allocator.
+ *   Use {rb_newobj_of}, {TypedData_Make_Struct} or others, instead.
+ * \note Usually prefer rb_class_new_instance to rb_obj_alloc and rb_obj_call_init
+ * \param[in] klass a Class object
+ * \sa rb_class_new_instance
+ * \sa rb_obj_call_init
+ * \sa rb_define_alloc_func
+ * \sa rb_newobj_of
+ * \sa TypedData_Make_Struct
+ */
 VALUE
 rb_obj_alloc(VALUE klass)
 {
@@ -1972,6 +2154,18 @@ rb_class_s_new(int argc, const VALUE *argv, VALUE klass)
     return obj;
 }
 
+/**
+ * Allocates and initializes an instance of \a klass.
+ *
+ * Equivalent to \c Class\#new in Ruby
+ *
+ * \param[in] argc  the number of arguments to \c #initialize
+ * \param[in] argv  a pointer to an array of arguments to \c #initialize
+ * \param[in] klass a Class object
+ * \return the new instance of \a klass
+ * \sa rb_obj_call_init
+ * \sa rb_obj_alloc
+ */
 VALUE
 rb_class_new_instance(int argc, const VALUE *argv, VALUE klass)
 {
@@ -1979,7 +2173,7 @@ rb_class_new_instance(int argc, const VALUE *argv, VALUE klass)
     return rb_class_s_new(argc, argv, klass);
 }
 
-/*
+/**
  *  call-seq:
  *     class.superclass -> a_super_class or nil
  *
@@ -1996,6 +2190,14 @@ rb_class_new_instance(int argc, const VALUE *argv, VALUE klass)
  *
  *     BasicObject.superclass   #=> nil
  *
+ *--
+ * Returns the superclass of \a klass. Equivalent to \c Class\#superclass in Ruby.
+ *
+ * It skips modules.
+ * \param[in] klass a Class object
+ * \return the superclass, or \c Qnil if \a klass does not have a parent class.
+ * \sa rb_class_get_superclass
+ *++
  */
 
 VALUE
@@ -2016,14 +2218,23 @@ rb_class_superclass(VALUE klass)
     return super;
 }
 
+/**
+ * Returns the superclass of \a klass
+ * The return value might be an iclass of a module, unlike rb_class_superclass.
+ *
+ * Also it returns Qfalse when \a klass does not have a parent class.
+ * \sa rb_class_superclass
+ */
 VALUE
 rb_class_get_superclass(VALUE klass)
 {
     return RCLASS(klass)->super;
 }
 
+/*! \private */
 #define id_for_var(obj, name, part, type) \
     id_for_setter(obj, name, type, "`%1$s' is not allowed as "#part" "#type" variable name")
+/*! \private */
 #define id_for_setter(obj, name, type, message) \
     check_setter_id(obj, &(name), rb_is_##type##_id, rb_is_##type##_name, message, strlen(message))
 static ID
@@ -2088,6 +2299,19 @@ rb_mod_attr_reader(int argc, VALUE *argv, VALUE klass)
     return Qnil;
 }
 
+/**
+ *  call-seq:
+ *    attr(name, ...) -> nil
+ *    attr(name, true) -> nil
+ *    attr(name, false) -> nil
+ *
+ *  The first form is equivalent to <code>attr_reader</code>.
+ *  The second form is equivalent to <code>attr_accessor(name)</code> but deprecated.
+ *  The last form is equivalent to <code>attr_reader(name)</code> but deprecated.
+ *--
+ * \private
+ *++
+ */
 VALUE
 rb_mod_attr(int argc, VALUE *argv, VALUE klass)
 {
@@ -2639,6 +2863,7 @@ rb_mod_singleton_p(VALUE klass)
     return Qfalse;
 }
 
+/*! \private */
 static const struct conv_method_tbl {
     const char method[6];
     unsigned short id;
@@ -2703,6 +2928,7 @@ convert_type(VALUE val, const char *tname, const char *method, int raise)
     return convert_type_with_id(val, tname, m, raise, i);
 }
 
+/*! \private */
 NORETURN(static void conversion_mismatch(VALUE, const char *, const char *, VALUE));
 static void
 conversion_mismatch(VALUE val, const char *tname, const char *method, VALUE result)
@@ -2713,6 +2939,19 @@ conversion_mismatch(VALUE val, const char *tname, const char *method, VALUE resu
 	     cname, tname, cname, method, rb_obj_class(result));
 }
 
+/*!
+ * Converts an object into another type.
+ * Calls the specified conversion method if necessary.
+ *
+ * \param[in] val   the object to be converted
+ * \param[in] type   a value of \c ruby_value_type
+ * \param[in] tname  name of the target type.
+ *   only used for error messages.
+ * \param[in] method name of the method
+ * \return an object of the specified type
+ * \throw TypeError on failure
+ * \sa rb_check_convert_type
+ */
 VALUE
 rb_convert_type(VALUE val, int type, const char *tname, const char *method)
 {
@@ -2726,6 +2965,7 @@ rb_convert_type(VALUE val, int type, const char *tname, const char *method)
     return v;
 }
 
+/*! \private */
 VALUE
 rb_convert_type_with_id(VALUE val, int type, const char *tname, ID method)
 {
@@ -2739,6 +2979,20 @@ rb_convert_type_with_id(VALUE val, int type, const char *tname, ID method)
     return v;
 }
 
+/*!
+ * Tries to convert an object into another type.
+ * Calls the specified conversion method if necessary.
+ *
+ * \param[in] val   the object to be converted
+ * \param[in] type   a value of \c ruby_value_type
+ * \param[in] tname  name of the target type.
+ *   only used for error messages.
+ * \param[in] method name of the method
+ * \return an object of the specified type, or Qnil if no such conversion method defined.
+ * \throw TypeError if the conversion method returns an unexpected type of value.
+ * \sa rb_convert_type
+ * \sa rb_check_convert_type_with_id
+ */
 VALUE
 rb_check_convert_type(VALUE val, int type, const char *tname, const char *method)
 {
@@ -2754,6 +3008,7 @@ rb_check_convert_type(VALUE val, int type, const char *tname, const char *method
     return v;
 }
 
+/*! \private */
 VALUE
 rb_check_convert_type_with_id(VALUE val, int type, const char *tname, ID method)
 {
@@ -2784,6 +3039,16 @@ rb_to_integer(VALUE val, const char *method)
     return v;
 }
 
+/**
+ * Tries to convert \a val into \c Integer.
+ * It calls the specified conversion method if necessary.
+ *
+ * \param[in] val     a Ruby object
+ * \param[in] method  a name of a method
+ * \return an \c Integer object on success,
+ *   or \c Qnil if no such conversion method defined.
+ * \exception TypeError if the conversion method returns a non-Integer object.
+ */
 VALUE
 rb_check_to_integer(VALUE val, const char *method)
 {
@@ -2798,12 +3063,29 @@ rb_check_to_integer(VALUE val, const char *method)
     return v;
 }
 
+/**
+ * Converts \a val into \c Integer.
+ * It calls \a #to_int method if necessary.
+ *
+ * \param[in] val a Ruby object
+ * \return an \c Integer object
+ * \exception TypeError on failure
+ */
 VALUE
 rb_to_int(VALUE val)
 {
     return rb_to_integer(val, "to_int");
 }
 
+/**
+ * Tries to convert \a val into Integer.
+ * It calls \c #to_int method if necessary.
+ *
+ * \param[in] val a Ruby object
+ * \return an Integer object on success,
+ *   or \c Qnil if \c #to_int is not defined.
+ * \exception TypeError if \c #to_int returns a non-Integer object.
+ */
 VALUE
 rb_check_to_int(VALUE val)
 {
@@ -2847,6 +3129,12 @@ rb_convert_to_integer(VALUE val, int base)
 
 }
 
+/**
+ * Equivalent to \c Kernel\#Integer in Ruby.
+ *
+ * Converts \a val into \c Integer in a slightly more strict manner
+ * than \c #to_i.
+ */
 VALUE
 rb_Integer(VALUE val)
 {
@@ -2896,6 +3184,17 @@ rb_f_integer(int argc, VALUE *argv, VALUE obj)
     return rb_convert_to_integer(arg, base);
 }
 
+/*!
+ * Parses a string representation of a floating point number.
+ *
+ * \param[in] p  a string representation of a floating number
+ * \param[in] badcheck raises an exception on parse error if \a badcheck is non-zero.
+ * \return the floating point number in the string on success,
+ *   0.0 on parse error and \a badcheck is zero.
+ * \note it always fails to parse a hexadecimal representation like "0xAB.CDp+1" when
+ *   \a badcheck is zero, even though it would success if \a badcheck was non-zero.
+ *   This inconsistency is coming from a historical compatibility reason. [ruby-dev:40822]
+ */
 double
 rb_cstr_to_dbl(const char *p, int badcheck)
 {
@@ -2975,6 +3274,17 @@ rb_cstr_to_dbl(const char *p, int badcheck)
     return d;
 }
 
+/*!
+ * Parses a string representation of a floating point number.
+ *
+ * \param[in] str  a \c String object representation of a floating number
+ * \param[in] badcheck raises an exception on parse error if \a badcheck is non-zero.
+ * \return the floating point number in the string on success,
+ *   0.0 on parse error and \a badcheck is zero.
+ * \note it always fails to parse a hexadecimal representation like "0xAB.CDp+1" when
+ *   \a badcheck is zero, even though it would success if \a badcheck was non-zero.
+ *   This inconsistency is coming from a historical compatibility reason. [ruby-dev:40822]
+ */
 double
 rb_str_to_dbl(VALUE str, int badcheck)
 {
@@ -3003,6 +3313,7 @@ rb_str_to_dbl(VALUE str, int badcheck)
     return ret;
 }
 
+/*! \cond INTERNAL_MACRO */
 #define fix2dbl_without_to_f(x) (double)FIX2LONG(x)
 #define big2dbl_without_to_f(x) rb_big2dbl(x)
 #define int2dbl_without_to_f(x) \
@@ -3020,6 +3331,7 @@ rb_str_to_dbl(VALUE str, int badcheck)
       case Qfalse: \
 	rb_raise_static(rb_eTypeError, pre "false" post); \
     }
+/*! \endcond */
 
 static inline void
 conversion_to_float(VALUE val)
@@ -3067,6 +3379,12 @@ to_float(VALUE *valp)
     return T_NONE;
 }
 
+/*!
+ * Equivalent to \c Kernel\#Float in Ruby.
+ *
+ * Converts \a val into \c Float in a slightly more strict manner
+ * than \c #to_f.
+ */
 VALUE
 rb_Float(VALUE val)
 {
@@ -3079,7 +3397,7 @@ rb_Float(VALUE val)
     return rb_convert_type(val, T_FLOAT, "Float", "to_f");
 }
 
-FUNC_MINIMIZED(static VALUE rb_f_float(VALUE obj, VALUE arg));
+FUNC_MINIMIZED(static VALUE rb_f_float(VALUE obj, VALUE arg)); /*!< \private */
 
 /*
  *  call-seq:
@@ -3112,6 +3430,11 @@ numeric_to_float(VALUE val)
     return rb_convert_type(val, T_FLOAT, "Float", "to_f");
 }
 
+/*!
+ * Converts a \c Numeric object into \c Float.
+ * \param[in] val a \c Numeric object
+ * \exception TypeError if \a val is not a \c Numeric or other conversion failures.
+ */
 VALUE
 rb_to_float(VALUE val)
 {
@@ -3122,6 +3445,13 @@ rb_to_float(VALUE val)
     return numeric_to_float(val);
 }
 
+/*!
+ * Tries to convert an object into \c Float.
+ * It calls \c #to_f if necessary.
+ *
+ * It returns \c Qnil if the object is not a \c Numeric
+ * or \c #to_f is not defined on the object.
+ */
 VALUE
 rb_check_to_float(VALUE val)
 {
@@ -3140,6 +3470,7 @@ basic_to_f_p(VALUE klass)
     return rb_method_basic_definition_p(klass, id_to_f);
 }
 
+/*! \private */
 double
 rb_num_to_dbl(VALUE val)
 {
@@ -3173,6 +3504,13 @@ rb_num_to_dbl(VALUE val)
     return RFLOAT_VALUE(val);
 }
 
+/*!
+ * Converts a \c Numeric object to \c double.
+ * \param[in] val a \c Numeric object
+ * \return the converted value
+ * \exception TypeError if \a val is not a \c Numeric or
+ *   it does not support conversion to a floating point number.
+ */
 double
 rb_num2dbl(VALUE val)
 {
@@ -3203,6 +3541,12 @@ rb_num2dbl(VALUE val)
     return RFLOAT_VALUE(val);
 }
 
+/*!
+ * Equivalent to \c Kernel\#String in Ruby.
+ *
+ * Converts \a val into \c String by trying \c #to_str at first and
+ * then trying \c #to_s.
+ */
 VALUE
 rb_String(VALUE val)
 {
@@ -3232,6 +3576,9 @@ rb_f_string(VALUE obj, VALUE arg)
     return rb_String(arg);
 }
 
+/*!
+ * Equivalent to \c Kernel\#Array in Ruby.
+ */
 VALUE
 rb_Array(VALUE val)
 {
@@ -3263,6 +3610,9 @@ rb_f_array(VALUE obj, VALUE arg)
     return rb_Array(arg);
 }
 
+/**
+ * Equivalent to \c Kernel\#Hash in Ruby
+ */
 VALUE
 rb_Hash(VALUE val)
 {
@@ -3298,6 +3648,7 @@ rb_f_hash(VALUE obj, VALUE arg)
     return rb_Hash(arg);
 }
 
+/*! \private */
 struct dig_method {
     VALUE klass;
     int basic;
@@ -3325,6 +3676,7 @@ no_dig_method(int found, VALUE recv, ID mid, int argc, const VALUE *argv, VALUE
     }
 }
 
+/*! \private */
 VALUE
 rb_obj_dig(int argc, VALUE *argv, VALUE obj, VALUE notfound)
 {
@@ -3423,24 +3775,6 @@ rb_obj_dig(int argc, VALUE *argv, VALUE obj, VALUE notfound)
  */
 
 
-/*!
- * Initializes the world of objects and classes.
- *
- * At first, the function bootstraps the class hierarchy.
- * It initializes the most fundamental classes and their metaclasses.
- * - \c BasicObject
- * - \c Object
- * - \c Module
- * - \c Class
- * After the bootstrap step, the class hierarchy becomes as the following
- * diagram.
- *
- * \image html boottime-classes.png
- *
- * Then, the function defines classes, modules and methods as usual.
- * \ingroup class
- */
-
 /*  Document-class: BasicObject
  *
  *  BasicObject is the parent class of all classes in Ruby.  It's an explicit
@@ -3513,6 +3847,27 @@ rb_obj_dig(int argc, VALUE *argv, VALUE obj, VALUE notfound)
  *  <code>:name</code>).
  */
 
+/*!
+ *--
+ * \private
+ * Initializes the world of objects and classes.
+ *
+ * At first, the function bootstraps the class hierarchy.
+ * It initializes the most fundamental classes and their metaclasses.
+ * - \c BasicObject
+ * - \c Object
+ * - \c Module
+ * - \c Class
+ * After the bootstrap step, the class hierarchy becomes as the following
+ * diagram.
+ *
+ * \image html boottime-classes.png
+ *
+ * Then, the function defines classes, modules and methods as usual.
+ * \ingroup class
+ *++
+ */
+
 void
 InitVM_Object(void)
 {
@@ -3747,3 +4102,7 @@ Init_Object(void)
     id_dig = rb_intern_const("dig");
     InitVM(Object);
 }
+
+/*!
+ * \}
+ */