From 9a1e9edd487ed880845cfdee58179fb04ca900ad Mon Sep 17 00:00:00 2001 From: yugui Date: Sat, 29 Aug 2009 13:39:44 +0000 Subject: Doxygen comment. git-svn-id: http://svn.ruby-lang.org/repos/ruby/trunk@24703 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- class.c | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ vm_eval.c | 59 +++++++++++++++++++ 2 files changed, 255 insertions(+) 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: + *
+ *
Fixed number of parameters
+ *
+ * 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 + *
+ *
argc and argv style
+ *
+ * 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 + *
+ *
Ruby array style
+ *
+ * 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 + *
+ * + * \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: + *
+ *
zero or positive number
+ *
This means the method body function takes a fixed number of parameters
+ *
-1
+ *
This means the method body function is "argc and argv" style.
+ *
-2
+ *
This means the method body function is "self and args" style.
+ *
+ * \{ + */ + 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) { -- cgit