ruby-changes:67720
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:00:59 +0900 (JST)
Subject: [ruby-changes:67720] 00ff6b68e4 (master): include/ruby/internal/method.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=00ff6b68e4 From 00ff6b68e4c2de55b175a5723d14269602cf163a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?= <shyouhei@r...> Date: Mon, 21 Dec 2020 14:43:55 +0900 Subject: 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. --- class.c | 78 +----------------- include/ruby/internal/method.h | 177 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 172 insertions(+), 83 deletions(-) diff --git a/class.c b/class.c index 35f9b86..d0f9152 100644 --- a/class.c +++ b/class.c @@ -1681,56 +1681,7 @@ rb_obj_singleton_methods(int argc, const VALUE *argv, VALUE obj) https://github.com/ruby/ruby/blob/trunk/class.c#L1681 * \} */ /*! - * \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), https://github.com/ruby/ruby/blob/trunk/class.c#L1907 #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) https://github.com/ruby/ruby/blob/trunk/class.c#L1917 #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) { diff --git a/include/ruby/internal/method.h b/include/ruby/internal/method.h index 8ada0e0..dcd3872 100644 --- a/include/ruby/internal/method.h +++ b/include/ruby/internal/method.h @@ -20,19 +20,184 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/method.h#L20 * extension libraries. They could be written in C++98. * @brief Creation and modification of Ruby methods. */ +#include "ruby/internal/attr/nonnull.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" #include "ruby/backward/2/stdarg.h" +/** + * @defgroup defmethod Defining methods + * + * There are some APIs to define a method from C. + * These API takes a C function as a method body. + * + * ### 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. + * + * ```CXX + * static VALUE my_method(VALUE self, VALUE x, VALUE y); + * ``` + * + * #### argc and argv style + * + * This form takes three parameters: argc, argv and self. + * self is the receiver. argc is the number of arguments. + * argv is a pointer to an array of the arguments. + * + * ```CXX + * static VALUE my_method(int argc, VALUE *argv, VALUE self); + * ``` + * + * #### Ruby array style + * + * This form takes two parameters: self and args. + * self is the receiver. args is an Array object which + * contains the arguments. + * + * ```CXX + * static VALUE my_method(VALUE self, VALUE args); + * ``` + * + * ### Number of parameters + * + * Method defining APIs takes the number of parameters which the + * method will takes. This number is called argc. + * 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. + * + * @{ + */ + RBIMPL_SYMBOL_EXPORT_BEGIN() -void rb_define_method(VALUE,const char*,VALUE(*)(ANYARGS),int); -void rb_define_module_function(VALUE,const char*,VALUE(*)(ANYARGS),int); -void rb_define_global_function(const char*,VALUE(*)(ANYARGS),int); +RBIMPL_ATTR_NONNULL(()) +/** + * Defines a method. + * + * @param[out] klass A module or a class. + * @param[in] mid Name of the function. + * @param[in] func The method body. + * @param[in] arity The number of parameters. See @ref defmethod. + * @note There are in fact 18 different prototypes for func. + * @see ::ruby::backward::cxxanyargs::define_method::rb_define_method + */ +void rb_define_method(VALUE klass, const char *mid, VALUE (*func)(ANYARGS), int arity); + +RBIMPL_ATTR_NONNULL(()) +/** + * Defines a module function for a module. + * + * @param[out] klass A module or a class. + * @param[in] mid Name of the function. + * @param[in] func The method body. + * @param[in] arity The number of parameters. See @ref defmethod. + * @note There are in fact 18 different prototypes for func. + * @see ::ruby::backward::cxxanyargs::define_method::rb_define_module_function + */ +void rb_define_module_function(VALUE klass, const char *mid, VALUE (*func)(ANYARGS), int arity); + +RBIMPL_ATTR_NONNULL(()) +/** + * Defines a global function. + * + * @param[in] mid Name of the function. + * @param[in] func The method body. + * @param[in] arity The number of parameters. See @ref defmethod. + * @note There are in fact 18 different prototypes for func. + * @see ::ruby::backward::cxxanyargs::define_method::rb_define_global_function + */ +void rb_define_global_function(const char *mid, VALUE (*func)(ANYARGS), int arity); + +RBIMPL_ATTR_NONNULL(()) +/** + * Defines an undef of a method. -- What? + * + * In ruby, there are two separate concepts called "undef" and "remove_method". + * The thing you imagine when you "un-define" a method is remove_method. This + * one on the other hand is masking of a previous method definition. Suppose + * for instance: + * + * ```ruby + * class Foo + * def foo + * end + * end + * + * class Bar < Foo + * def bar + * foo + * end + * end + * + * class Baz < Foo + * undef foo # <--- (*1) + * end + * ``` + * + * This `undef foo` at `(*1)` must not eliminate `Foo#foo`, because that method + * is also used from `Bar#bar`. So instead of physically executing the target + * method, `undef` inserts a special filtering entry to the class (`Baz` this + * case). That entry, when called, acts as if there were no methods at all. + * But the original can still be accessible, via ways like `Bar#bar` above. + * + * @param[out] klass The class to insert an undef. + * @param[in] name Name of the undef. + * @exception rb_eTypeError `klass` is a non-module. + * @exception rb_eFrozenError `klass` is frozen. + */ +void rb_undef_method(VALUE klass, const char *name); + +RBIMPL_ATTR_NONNULL(()) +/** + * Defines an alias of a method. + * + * @param[in,out] klass The class which the original method belongs + * to; this is also where the new method will + * belong to. + * @param[in] dst A new name for the method. + (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/