Doxygen comment.

git-svn-id: http://svn.ruby-lang.org/repos/ruby/trunk@24703 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

2 files changed, 255 insertions, 0 deletions

diff --git a/class.c b/class.c
index 1ffb61a46..e46d1e224 100644
--- a/class.c
+++ b/class.c
@@ -303,6 +303,17 @@ rb_make_metaclass(VALUE obj, VALUE super)
     }
 }
 
+
+/*!
+ * Defines a new class.
+ * \param id     ignored
+ * \param super  A class from which the new class will derive. NULL means \c Object class.
+ * \return       the created class
+ * \throw TypeError if super is not a \c Class object.
+ *
+ * \note the returned class will not be associated with \a id.
+ *       You must explicitly set a class name if necessary.
+ */
 VALUE
 rb_define_class_id(ID id, VALUE super)
 {
@@ -315,6 +326,15 @@ rb_define_class_id(ID id, VALUE super)
     return klass;
 }
 
+
+/*!
+ * Calls Class#inherited.
+ * \param super  A class which will be called #inherited.
+ *               NULL means Object class.
+ * \param klass  A Class object which derived from \a super
+ * \return the value \c Class#inherited's returns
+ * \pre Each of \a super and \a klass must be a \c Class object.
+ */
 VALUE
 rb_class_inherited(VALUE super, VALUE klass)
 {
@@ -324,6 +344,23 @@ rb_class_inherited(VALUE super, VALUE klass)
     return rb_funcall(super, inherited, 1, klass);
 }
 
+
+
+/*!
+ * Defines a top-level class.
+ * \param name   name of the class
+ * \param super  a class from which the new class will derive. 
+ *               NULL means \c Object class.
+ * \return the created class
+ * \throw TypeError if the constant name \a name is already taken but 
+ *                  the constant is not a \c Class.
+ * \throw NameError if the class is already defined but the class can not
+ *                  be reopened because its superclass is not \a super.
+ * \post top-level constant named \a name refers the returned class.
+ *
+ * \note if a class named \a name is already defined and its superclass is
+ *       \a super, the function just returns the defined class.
+ */
 VALUE
 rb_define_class(const char *name, VALUE super)
 {
@@ -353,12 +390,46 @@ rb_define_class(const char *name, VALUE super)
     return klass;
 }
 
+
+/*!
+ * Defines a class under the namespace of \a outer.
+ * \param outer  a class which contains the new class.
+ * \param name   name of the new class
+ * \param super  a class from which the new class will derive. 
+ *               NULL means \c Object class.
+ * \return the created class
+ * \throw TypeError if the constant name \a name is already taken but 
+ *                  the constant is not a \c Class.
+ * \throw NameError if the class is already defined but the class can not
+ *                  be reopened because its superclass is not \a super.
+ * \post top-level constant named \a name refers the returned class.
+ *
+ * \note if a class named \a name is already defined and its superclass is
+ *       \a super, the function just returns the defined class.
+ */
 VALUE
 rb_define_class_under(VALUE outer, const char *name, VALUE super)
 {
     return rb_define_class_id_under(outer, rb_intern(name), super);
 }
 
+
+/*!
+ * Defines a class under the namespace of \a outer.
+ * \param outer  a class which contains the new class.
+ * \param id     name of the new class
+ * \param super  a class from which the new class will derive. 
+ *               NULL means \c Object class.
+ * \return the created class
+ * \throw TypeError if the constant name \a name is already taken but 
+ *                  the constant is not a \c Class.
+ * \throw NameError if the class is already defined but the class can not
+ *                  be reopened because its superclass is not \a super.
+ * \post top-level constant named \a name refers the returned class.
+ *
+ * \note if a class named \a name is already defined and its superclass is
+ *       \a super, the function just returns the defined class.
+ */
 VALUE
 rb_define_class_id_under(VALUE outer, ID id, VALUE super)
 {
@@ -870,6 +941,63 @@ rb_obj_singleton_methods(int argc, VALUE *argv, VALUE obj)
     return ary;
 }
 
+/*!
+ * \}
+ */
+/*!
+ * \defgroup defmethod Defining methods
+ * There are some APIs to define a method from C.
+ * These API takes a C function as a method body.
+ *
+ * \par Method body functions
+ * Method body functions must return a VALUE and 
+ * can be one of the following form:
+ * <dl>
+ * <dt>Fixed number of parameters</dt>
+ * <dd>
+ *     This form is a normal C function, excepting it takes 
+ *     a receiver object as the first argument.
+ *
+ *     \code
+ *     static VALUE my_method(VALUE self, VALUE x, VALUE y);
+ *     \endcode
+ * </dd>
+ * <dt>argc and argv style</dt>
+ * <dd>
+ *     This form takes three parameters: \a argc, \a argv and \a self.
+ *     \a self is the receiver. \a argc is the number of arguments.
+ *     \a argv is a pointer to an array of the arguments.
+ *
+ *     \code
+ *     static VALUE my_method(int argc, VALUE *argv, VALUE self);
+ *     \endcode
+ * </dd>
+ * <dt>Ruby array style</dt>
+ * <dd>
+ *     This form takes two parameters: self and args.
+ *     \a self is the receiver. \a args is an Array object which 
+ *     containts the arguments.
+ *
+ *     \code
+ *     static VALUE my_method(VALUE self, VALUE args);
+ *     \endcode
+ * </dd>
+ *
+ * \par Number of parameters
+ * Method defining APIs takes the number of parameters which the
+ * method will takes. This number is called \a argc.
+ * \a argc can be:
+ * <dl>
+ * <dt>zero or positive number</dt>
+ * <dd>This means the method body function takes a fixed number of parameters</dd>
+ * <dt>-1</dt>
+ * <dd>This means the method body function is "argc and argv" style.</dd>
+ * <dt>-2</dt>
+ * <dd>This means the method body function is "self and args" style.</dd>
+ * </dl>
+ * \{
+ */
+
 void
 rb_define_method_id(VALUE klass, ID mid, VALUE (*func)(ANYARGS), int argc)
 {
@@ -900,12 +1028,34 @@ rb_undef_method(VALUE klass, const char *name)
     rb_add_method(klass, rb_intern(name), VM_METHOD_TYPE_UNDEF, 0, NOEX_UNDEF);
 }
 
+/*!
+ * \}
+ */
+/*!
+ * \addtogroup class
+ * \{
+ */
+
 #define SPECIAL_SINGLETON(x,c) do {\
     if (obj == (x)) {\
 	return c;\
     }\
 } while (0)
 
+
+/*!
+ * Returns the singleton class of \a obj.
+ *
+ * \param obj an arbitrary object.
+ * \throw TypeError if \a obj is a Fixnum or a Symbol.
+ * \return the singleton class.
+ *
+ * \post \a obj has the singleton class.
+ * \note a new singleton class will be created 
+ *       if \a obj does not have it.
+ * \note the singleton classes for nil, true and false are:
+ *       NilClass, TrueClass and FalseClass.
+ */
 VALUE
 rb_singleton_class(VALUE obj)
 {
@@ -952,12 +1102,37 @@ rb_singleton_class(VALUE obj)
     return klass;
 }
 
+/*!
+ * \}
+ */
+
+/*!
+ * \addtogroup defmethod
+ * \{
+ */
+
+/*!
+ * Defines a singleton method for \a obj.
+ * \param obj    an arbitrary object
+ * \param name   name of the singleton method
+ * \param func   the method body
+ * \param argc   the number of parameters, or -1 or -2. see \ref defmethod.
+ */
 void
 rb_define_singleton_method(VALUE obj, const char *name, VALUE (*func)(ANYARGS), int argc)
 {
     rb_define_method(rb_singleton_class(obj), name, func, argc);
 }
 
+
+
+/*!
+ * Defines a module function for \a module.
+ * \param module  an module or a class.
+ * \param name    name of the function
+ * \param func    the method body
+ * \param argc    the number of parameters, or -1 or -2. see \ref defmethod.
+ */
 void
 rb_define_module_function(VALUE module, const char *name, VALUE (*func)(ANYARGS), int argc)
 {
@@ -965,18 +1140,39 @@ rb_define_module_function(VALUE module, const char *name, VALUE (*func)(ANYARGS)
     rb_define_singleton_method(module, name, func, argc);
 }
 
+
+/*!
+ * Defines a global function
+ * \param name    name of the function
+ * \param func    the method body
+ * \param argc    the number of parameters, or -1 or -2. see \ref defmethod.
+ */
 void
 rb_define_global_function(const char *name, VALUE (*func)(ANYARGS), int argc)
 {
     rb_define_module_function(rb_mKernel, name, func, argc);
 }
 
+
+/*!
+ * Defines an alias of a method.
+ * \param klass  the class which the original method belongs to
+ * \param name1  a new name for the method
+ * \param name2  the original name of the method
+ */
 void
 rb_define_alias(VALUE klass, const char *name1, const char *name2)
 {
     rb_alias(klass, rb_intern(name1), rb_intern(name2));
 }
 
+/*!
+ * Defines (a) public accessor method(s) for an attribute.
+ * \param klass  the class which the attribute will belongs to
+ * \param name   name of the attribute
+ * \param read   a getter method for the attribute will be defined if \a read is non-zero.
+ * \param write  a setter method for the attribute will be defined if \a write is non-zero.
+ */
 void
 rb_define_attr(VALUE klass, const char *name, int read, int write)
 {
diff --git a/vm_eval.c b/vm_eval.c
index cad6de449..fa802ad04 100644
--- a/vm_eval.c
+++ b/vm_eval.c
@@ -191,6 +191,20 @@ stack_check(void)
     }
 }
 
+/*!
+ * \internal
+ * calls the specified method.
+ *
+ * This function is called by functions in rb_call* family.
+ * \param recv   receiver of the method
+ * \param mid    an ID that represents the name of the method
+ * \param argc   the number of method arguments
+ * \param argv   a pointer to an array of method arguments
+ * \param scope  
+ * \param self   self in the caller. Qundef means the current control frame's self.
+ *
+ * \note \a self is used in order to controlling access to protected methods.
+ */
 static inline VALUE
 rb_call0(VALUE recv, ID mid, int argc, const VALUE *argv,
 	 call_type scope, VALUE self)
@@ -269,6 +283,18 @@ rb_call0(VALUE recv, ID mid, int argc, const VALUE *argv,
     return vm_call0(th, recv, mid, argc, argv, me);
 }
 
+
+/*!
+ * \internal
+ * calls the specified method.
+ *
+ * This function is called by functions in rb_call* family.
+ * \param recv   receiver
+ * \param mid    an ID that represents the name of the method
+ * \param argc   the number of method arguments
+ * \param argv   a pointer to an array of method arguments
+ * \param scope  
+ */
 static inline VALUE
 rb_call(VALUE recv, ID mid, int argc, const VALUE *argv, call_type scope)
 {
@@ -412,6 +438,14 @@ rb_raise_method_missing(rb_thread_t *th, int argc, VALUE *argv,
     raise_method_missing(th, argc, argv, obj, call_status | NOEX_MISSING);
 }
 
+/*!
+ * Calls a method
+ * \param recv   receiver of the method
+ * \param mid    an ID that represents the name of the method
+ * \param args   an Array object which contains method arguments
+ *
+ * \pre \a args must refer an Array object.
+ */
 VALUE
 rb_apply(VALUE recv, ID mid, VALUE args)
 {
@@ -424,6 +458,15 @@ rb_apply(VALUE recv, ID mid, VALUE args)
     return rb_call(recv, mid, argc, argv, CALL_FCALL);
 }
 
+/*!
+ * Calls a method
+ * \param recv   receiver of the method
+ * \param mid    an ID that represents the name of the method
+ * \param n      the number of arguments
+ * \param ...    arbitrary number of method arguments
+ *
+ * \pre each of arguments after \a n must be a VALUE.
+ */
 VALUE
 rb_funcall(VALUE recv, ID mid, int n, ...)
 {
@@ -447,12 +490,28 @@ rb_funcall(VALUE recv, ID mid, int n, ...)
     return rb_call(recv, mid, n, argv, CALL_FCALL);
 }
 
+/*!
+ * Calls a method
+ * \param recv   receiver of the method
+ * \param mid    an ID that represents the name of the method
+ * \param argc   the number of arguments
+ * \param argv   pointer to an array of method arguments
+ */
 VALUE
 rb_funcall2(VALUE recv, ID mid, int argc, const VALUE *argv)
 {
     return rb_call(recv, mid, argc, argv, CALL_FCALL);
 }
 
+/*!
+ * Calls a method.
+ *
+ * Same as rb_funcall2 but this function can call only public methods.
+ * \param recv   receiver of the method
+ * \param mid    an ID that represents the name of the method
+ * \param argc   the number of arguments
+ * \param argv   pointer to an array of method arguments
+ */
 VALUE
 rb_funcall3(VALUE recv, ID mid, int argc, const VALUE *argv)
 {