include/ruby/internal/method.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]

In fact many functions declared in the header file are already
documented more or less.  They were just copy & pasted, with applying
some style updates.

1 files changed, 1 insertions, 77 deletions

diff --git a/class.c b/class.c
index 35f9b862ff..d0f91528b4 100644
--- a/class.c
+++ b/class.c
@@ -1681,56 +1681,7 @@ rb_obj_singleton_methods(int argc, const VALUE *argv, VALUE obj)
  * \}
  */
 /*!
- * \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
- *     contains 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>
+ * \addtogroup defmethod
  * \{
  */
 
@@ -1956,13 +1907,6 @@ rb_define_singleton_method(VALUE obj, const char *name, VALUE (*func)(ANYARGS),
 #ifdef rb_define_module_function
 #undef rb_define_module_function
 #endif
-/*!
- * 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)
 {
@@ -1973,38 +1917,18 @@ rb_define_module_function(VALUE module, const char *name, VALUE (*func)(ANYARGS)
 #ifdef rb_define_global_function
 #undef rb_define_global_function
 #endif
-/*!
- * 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)
 {