kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

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

Browse source 
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:
卜部昌平 2020-12-21 16:32:40 +09:00
parent 1f66d8a77b
commit 9ba9dbf168
Notes: git 2021-09-10 20:01:51 +09:00
3 changed files with 144 additions and 66 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
class.c
View file

@ -10,16 +10,7 @@
**********************************************************************/
/*!
* \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.
* \addtogroup class
* \{
*/
@ -734,23 +725,6 @@ 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.
* \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
rb_define_class(const char *name, VALUE super)
{
@ -783,24 +757,6 @@ 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 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
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();
}
/*!
* \note the compaction GC does not move modules returned by this function.
*/
VALUE
rb_define_module(const char *name)
{
@ -903,9 +856,6 @@ rb_define_module(const char *name)
return module;
}
/*!
* \note the compaction GC does not move modules returned by this function.
*/
VALUE
rb_define_module_under(VALUE outer, const char *name)
{

6
eval.c
View file

@ -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);
}
/*!
* Extend the object with the module.
*
* Same as \c Module\#extend_object.
* \ingroup class
*/
void
rb_extend_object(VALUE obj, VALUE module)
{

152
include/ruby/internal/module.h
View file

@ -23,20 +23,154 @@
#include "ruby/internal/dllexport.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_ATTR_NONNULL(())
/**
* GC compaction note: class and modules returned by these four functions
* do not move.
* Defines a top-level class.
*
* @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_module(const char*);
VALUE rb_define_class_under(VALUE, const char*, VALUE);
VALUE rb_define_module_under(VALUE, const char*);
VALUE rb_define_class(const char *name, VALUE super);
void rb_include_module(VALUE,VALUE);
void rb_extend_object(VALUE,VALUE);
void rb_prepend_module(VALUE,VALUE);
RBIMPL_ATTR_NONNULL(())
/**
* 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()