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
Download patch file Download diff file Expand all files Collapse all files

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()