mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
include/ruby/internal/module.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
1f66d8a77b
commit
9ba9dbf168
Notes:
git
2021-09-10 20:01:51 +09:00
3 changed files with 144 additions and 66 deletions
52
class.c
52
class.c
|
|
@ -10,16 +10,7 @@
|
||||||
**********************************************************************/
|
**********************************************************************/
|
||||||
|
|
||||||
/*!
|
/*!
|
||||||
* \defgroup class Classes and their hierarchy.
|
* \addtogroup class
|
||||||
* \par Terminology
|
|
||||||
* - class: same as in Ruby.
|
|
||||||
* - singleton class: class for a particular object
|
|
||||||
* - eigenclass: = singleton class
|
|
||||||
* - metaclass: class of a class. metaclass is a kind of singleton class.
|
|
||||||
* - metametaclass: class of a metaclass.
|
|
||||||
* - meta^(n)-class: class of a meta^(n-1)-class.
|
|
||||||
* - attached object: A singleton class knows its unique instance.
|
|
||||||
* The instance is called the attached object for the singleton class.
|
|
||||||
* \{
|
* \{
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
|
@ -734,23 +725,6 @@ rb_class_inherited(VALUE super, VALUE klass)
|
||||||
return rb_funcall(super, inherited, 1, 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.
|
|
||||||
* \return the created class
|
|
||||||
* \throw TypeError if the constant name \a name is already taken but
|
|
||||||
* the constant is not a \c Class.
|
|
||||||
* \throw TypeError if the class is already defined but the class can not
|
|
||||||
* be reopened because its superclass is not \a super.
|
|
||||||
* \throw ArgumentError if the \a super is NULL.
|
|
||||||
* \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
|
VALUE
|
||||||
rb_define_class(const char *name, VALUE super)
|
rb_define_class(const char *name, VALUE super)
|
||||||
{
|
{
|
||||||
|
|
@ -783,24 +757,6 @@ rb_define_class(const char *name, VALUE super)
|
||||||
return klass;
|
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 TypeError 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.
|
|
||||||
* \note the compaction GC does not move classes returned by this function.
|
|
||||||
*/
|
|
||||||
VALUE
|
VALUE
|
||||||
rb_define_class_under(VALUE outer, const char *name, VALUE super)
|
rb_define_class_under(VALUE outer, const char *name, VALUE super)
|
||||||
{
|
{
|
||||||
|
|
@ -876,9 +832,6 @@ rb_define_module_id(ID id)
|
||||||
return rb_module_new();
|
return rb_module_new();
|
||||||
}
|
}
|
||||||
|
|
||||||
/*!
|
|
||||||
* \note the compaction GC does not move modules returned by this function.
|
|
||||||
*/
|
|
||||||
VALUE
|
VALUE
|
||||||
rb_define_module(const char *name)
|
rb_define_module(const char *name)
|
||||||
{
|
{
|
||||||
|
|
@ -903,9 +856,6 @@ rb_define_module(const char *name)
|
||||||
return module;
|
return module;
|
||||||
}
|
}
|
||||||
|
|
||||||
/*!
|
|
||||||
* \note the compaction GC does not move modules returned by this function.
|
|
||||||
*/
|
|
||||||
VALUE
|
VALUE
|
||||||
rb_define_module_under(VALUE outer, const char *name)
|
rb_define_module_under(VALUE outer, const char *name)
|
||||||
{
|
{
|
||||||
|
|
|
||||||
6
eval.c
6
eval.c
|
|
@ -1713,12 +1713,6 @@ rb_obj_call_init_kw(VALUE obj, int argc, const VALUE *argv, int kw_splat)
|
||||||
rb_funcallv_kw(obj, idInitialize, argc, argv, kw_splat);
|
rb_funcallv_kw(obj, idInitialize, argc, argv, kw_splat);
|
||||||
}
|
}
|
||||||
|
|
||||||
/*!
|
|
||||||
* Extend the object with the module.
|
|
||||||
*
|
|
||||||
* Same as \c Module\#extend_object.
|
|
||||||
* \ingroup class
|
|
||||||
*/
|
|
||||||
void
|
void
|
||||||
rb_extend_object(VALUE obj, VALUE module)
|
rb_extend_object(VALUE obj, VALUE module)
|
||||||
{
|
{
|
||||||
|
|
|
||||||
|
|
@ -23,20 +23,154 @@
|
||||||
#include "ruby/internal/dllexport.h"
|
#include "ruby/internal/dllexport.h"
|
||||||
#include "ruby/internal/value.h"
|
#include "ruby/internal/value.h"
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @defgroup class Classes and their hierarchy.
|
||||||
|
*
|
||||||
|
* @par Terminology
|
||||||
|
* - class: same as in Ruby.
|
||||||
|
* - singleton class: class for a particular object.
|
||||||
|
* - eigenclass: = singleton class
|
||||||
|
* - metaclass: class of a class. Metaclass is a kind of singleton class.
|
||||||
|
* - metametaclass: class of a metaclass.
|
||||||
|
* - meta^(n)-class: class of a meta^(n-1)-class.
|
||||||
|
* - attached object: A singleton class knows its unique instance.
|
||||||
|
* The instance is called the attached object for the singleton class.
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
RBIMPL_SYMBOL_EXPORT_BEGIN()
|
RBIMPL_SYMBOL_EXPORT_BEGIN()
|
||||||
|
|
||||||
|
RBIMPL_ATTR_NONNULL(())
|
||||||
/**
|
/**
|
||||||
* GC compaction note: class and modules returned by these four functions
|
* Defines a top-level class.
|
||||||
* do not move.
|
*
|
||||||
|
* @param[in] name Name of the class.
|
||||||
|
* @param[in] super A class from which the new class will derive.
|
||||||
|
* @exception rb_eTypeError The constant name `name` is already taken but the
|
||||||
|
* constant is not a class.
|
||||||
|
* @exception rb_eTypeError The class is already defined but the class can
|
||||||
|
* not be reopened because its superclass is not
|
||||||
|
* `super`.
|
||||||
|
* @exception rb_eArgError `super` is NULL.
|
||||||
|
* @return The created class.
|
||||||
|
* @post Top-level constant named `name` refers the returned class.
|
||||||
|
* @note If a class named `name` is already defined and its superclass is
|
||||||
|
* `super`, the function just returns the defined class.
|
||||||
|
* @note The compaction GC does not move classes returned by this
|
||||||
|
* function.
|
||||||
|
*
|
||||||
|
* @internal
|
||||||
|
*
|
||||||
|
* There are classes without names, but you can't pass NULL here. You have to
|
||||||
|
* use other ways to create one.
|
||||||
*/
|
*/
|
||||||
VALUE rb_define_class(const char*,VALUE);
|
VALUE rb_define_class(const char *name, VALUE super);
|
||||||
VALUE rb_define_module(const char*);
|
|
||||||
VALUE rb_define_class_under(VALUE, const char*, VALUE);
|
|
||||||
VALUE rb_define_module_under(VALUE, const char*);
|
|
||||||
|
|
||||||
void rb_include_module(VALUE,VALUE);
|
RBIMPL_ATTR_NONNULL(())
|
||||||
void rb_extend_object(VALUE,VALUE);
|
/**
|
||||||
void rb_prepend_module(VALUE,VALUE);
|
* Defines a top-level module.
|
||||||
|
*
|
||||||
|
* @param[in] name Name of the module.
|
||||||
|
* @exception rb_eTypeError The constant name `name` is already taken but the
|
||||||
|
* constant is not a module.
|
||||||
|
* @return The created module.
|
||||||
|
* @post Top-level constant named `name` refers the returned module.
|
||||||
|
* @note The compaction GC does not move classes returned by this
|
||||||
|
* function.
|
||||||
|
*
|
||||||
|
* @internal
|
||||||
|
*
|
||||||
|
* There are modules without names, but you can't pass NULL here. You have to
|
||||||
|
* use other ways to create one.
|
||||||
|
*/
|
||||||
|
VALUE rb_define_module(const char *name);
|
||||||
|
|
||||||
|
RBIMPL_ATTR_NONNULL(())
|
||||||
|
/**
|
||||||
|
* Defines a class under the namespace of `outer`.
|
||||||
|
*
|
||||||
|
* @param[out] outer A class which contains the new class.
|
||||||
|
* @param[in] name Name of the new class
|
||||||
|
* @param[in] super A class from which the new class will derive.
|
||||||
|
* 0 means ::rb_cObject.
|
||||||
|
* @exception rb_eTypeError The constant name `name` is already taken but
|
||||||
|
* the constant is not a class.
|
||||||
|
* @exception rb_eTypeError The class is already defined but the class can
|
||||||
|
* not be reopened because its superclass is not
|
||||||
|
* `super`.
|
||||||
|
* @exception rb_eArgError `super` is NULL.
|
||||||
|
* @return The created class.
|
||||||
|
* @post `outer::name` refers the returned class.
|
||||||
|
* @note If a class named `name` is already defined and its superclass
|
||||||
|
* is `super`, the function just returns the defined class.
|
||||||
|
* @note The compaction GC does not move classes returned by this
|
||||||
|
* function.
|
||||||
|
*/
|
||||||
|
VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super);
|
||||||
|
|
||||||
|
RBIMPL_ATTR_NONNULL(())
|
||||||
|
/**
|
||||||
|
* Defines a module under the namespace of `outer`.
|
||||||
|
*
|
||||||
|
* @param[out] outer A class which contains the new module.
|
||||||
|
* @param[in] name Name of the new module
|
||||||
|
* @exception rb_eTypeError The constant name `name` is already taken but
|
||||||
|
* the constant is not a class.
|
||||||
|
* @return The created module.
|
||||||
|
* @post `outer::name` refers the returned module.
|
||||||
|
* @note The compaction GC does not move classes returned by this
|
||||||
|
* function.
|
||||||
|
*/
|
||||||
|
VALUE rb_define_module_under(VALUE outer, const char *name);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Includes a module to a class.
|
||||||
|
*
|
||||||
|
* @param[out] klass Inclusion destination.
|
||||||
|
* @param[in] module Inclusion source.
|
||||||
|
* @exception rb_eArgError Cyclic inclusion.
|
||||||
|
*
|
||||||
|
* @internal
|
||||||
|
*
|
||||||
|
* :FIXME: @shyouhei suspects this function lacks assertion that the arguments
|
||||||
|
* being modules... Could silently SEGV if non-module was passed?
|
||||||
|
*/
|
||||||
|
void rb_include_module(VALUE klass, VALUE module);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Extend the object with the module.
|
||||||
|
*
|
||||||
|
* @warning This is the same as `Module#extend_object`, not
|
||||||
|
* `Object#extend`! These two methods are very similar, but not
|
||||||
|
* identical. The difference is the hook. `Module#extend_object`
|
||||||
|
* does not invoke `Module#extended`, while `Object#extend` does.
|
||||||
|
* @param[out] obj Object to extend.
|
||||||
|
* @param[in] mod Module of extension.
|
||||||
|
*/
|
||||||
|
void rb_extend_object(VALUE obj, VALUE mod);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Identical to rb_include_module(), except it "prepends" the passed module to
|
||||||
|
* the klass, instead of includes. This affects how `super` resolves. For
|
||||||
|
* instance:
|
||||||
|
*
|
||||||
|
* ```ruby
|
||||||
|
* class Q; def foo; "<q/>" end end
|
||||||
|
* module W; def foo; "<w>#{super}</w>" end end
|
||||||
|
* class E < Q; include W; def foo; "<e>#{super}</e>" end end
|
||||||
|
* class R < Q; prepend W; def foo; "<r>#{super}</r>" end end
|
||||||
|
*
|
||||||
|
* E.new.foo # => "<e><w><q/></w></e>"
|
||||||
|
* r.new.foo # => "<W><r><q/></r></w>"
|
||||||
|
* ```
|
||||||
|
*
|
||||||
|
* @param[out] klass Target class to modify.
|
||||||
|
* @param[in] module Module to prepend.
|
||||||
|
* @exception rb_eArgError Cyclic inclusion.
|
||||||
|
*/
|
||||||
|
void rb_prepend_module(VALUE klass, VALUE module);
|
||||||
|
|
||||||
|
/** @} */
|
||||||
|
|
||||||
RBIMPL_SYMBOL_EXPORT_END()
|
RBIMPL_SYMBOL_EXPORT_END()
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue