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.
This commit is contained in:
卜部昌平
parent
9ba9dbf168
commit
00ff6b68e4
Notes:
git
2021-09-10 20:01:51 +09:00
78
class.c
78
class.c
@ -1681,56 +1681,7 @@ rb_obj_singleton_methods(int argc, const VALUE *argv, VALUE obj)
|
|||||||
* \}
|
* \}
|
||||||
*/
|
*/
|
||||||
/*!
|
/*!
|
||||||
* \defgroup defmethod Defining methods
|
* \addtogroup defmethod
|
||||||
* 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>
|
|
||||||
* \{
|
* \{
|
||||||
*/
|
*/
|
||||||
|
|
||||||
@ -1956,13 +1907,6 @@ rb_define_singleton_method(VALUE obj, const char *name, VALUE (*func)(ANYARGS),
|
|||||||
#ifdef rb_define_module_function
|
#ifdef rb_define_module_function
|
||||||
#undef rb_define_module_function
|
#undef rb_define_module_function
|
||||||
#endif
|
#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
|
void
|
||||||
rb_define_module_function(VALUE module, const char *name, VALUE (*func)(ANYARGS), int argc)
|
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
|
#ifdef rb_define_global_function
|
||||||
#undef rb_define_global_function
|
#undef rb_define_global_function
|
||||||
#endif
|
#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
|
void
|
||||||
rb_define_global_function(const char *name, VALUE (*func)(ANYARGS), int argc)
|
rb_define_global_function(const char *name, VALUE (*func)(ANYARGS), int argc)
|
||||||
{
|
{
|
||||||
rb_define_module_function(rb_mKernel, name, func, 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
|
void
|
||||||
rb_define_alias(VALUE klass, const char *name1, const char *name2)
|
rb_define_alias(VALUE klass, const char *name1, const char *name2)
|
||||||
{
|
{
|
||||||
rb_alias(klass, rb_intern(name1), rb_intern(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
|
void
|
||||||
rb_define_attr(VALUE klass, const char *name, int read, int write)
|
rb_define_attr(VALUE klass, const char *name, int read, int write)
|
||||||
{
|
{
|
||||||
|
|||||||
@ -20,19 +20,184 @@
|
|||||||
* extension libraries. They could be written in C++98.
|
* extension libraries. They could be written in C++98.
|
||||||
* @brief Creation and modification of Ruby methods.
|
* @brief Creation and modification of Ruby methods.
|
||||||
*/
|
*/
|
||||||
|
#include "ruby/internal/attr/nonnull.h"
|
||||||
#include "ruby/internal/dllexport.h"
|
#include "ruby/internal/dllexport.h"
|
||||||
#include "ruby/internal/value.h"
|
#include "ruby/internal/value.h"
|
||||||
#include "ruby/backward/2/stdarg.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()
|
RBIMPL_SYMBOL_EXPORT_BEGIN()
|
||||||
|
|
||||||
void rb_define_method(VALUE,const char*,VALUE(*)(ANYARGS),int);
|
RBIMPL_ATTR_NONNULL(())
|
||||||
void rb_define_module_function(VALUE,const char*,VALUE(*)(ANYARGS),int);
|
/**
|
||||||
void rb_define_global_function(const char*,VALUE(*)(ANYARGS),int);
|
* 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);
|
||||||
|
|
||||||
void rb_undef_method(VALUE,const char*);
|
RBIMPL_ATTR_NONNULL(())
|
||||||
void rb_define_alias(VALUE,const char*,const char*);
|
/**
|
||||||
void rb_define_attr(VALUE,const char*,int,int);
|
* 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.
|
||||||
|
* @param[in] src The original name of the method.
|
||||||
|
* @exception rb_eTypeError `klass` is a non-module.
|
||||||
|
* @exception rb_eFrozenError `klass` is frozen.
|
||||||
|
* @exception rb_eNameError There is no such method named as `src` in
|
||||||
|
* `klass`.
|
||||||
|
*
|
||||||
|
* @internal
|
||||||
|
*
|
||||||
|
* Above description is in fact a bit inaccurate because it ignores
|
||||||
|
* Refinements.
|
||||||
|
*/
|
||||||
|
void rb_define_alias(VALUE klass, const char *dst, const char *src);
|
||||||
|
|
||||||
|
RBIMPL_ATTR_NONNULL(())
|
||||||
|
/**
|
||||||
|
* Defines public accessor method(s) for an attribute.
|
||||||
|
*
|
||||||
|
* @param[out] klass The class which the attribute will belong to.
|
||||||
|
* @param[in] name Name of the attribute.
|
||||||
|
* @param[in] read Whether to define a getter method.
|
||||||
|
* @param[in] write Whether to define a setter method.
|
||||||
|
* @exception rb_eTypeError `klass` is a non-module.
|
||||||
|
* @exception rb_eFrozenError `klass` is frozen.
|
||||||
|
* @exception rb_eNameError `name` invalid as an attr e.g. an operator.
|
||||||
|
*/
|
||||||
|
void rb_define_attr(VALUE klass, const char *name, int read, int write);
|
||||||
|
|
||||||
|
/** @} */
|
||||||
|
|
||||||
RBIMPL_SYMBOL_EXPORT_END()
|
RBIMPL_SYMBOL_EXPORT_END()
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user