summaryrefslogtreecommitdiff
path: root/include/ruby/internal/module.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/ruby/internal/module.h')
-rw-r--r--include/ruby/internal/module.h152
1 files changed, 143 insertions, 9 deletions
diff --git a/include/ruby/internal/module.h b/include/ruby/internal/module.h
index f32e0b95ee..d678dd2102 100644
--- a/include/ruby/internal/module.h
+++ b/include/ruby/internal/module.h
@@ -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(())
+/**
+ * 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 *name, VALUE super);
+
+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);
+
/**
- * GC compaction note: class and modules returned by these four functions
- * do not move.
+ * 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.
*/
-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*);
+void rb_prepend_module(VALUE klass, VALUE module);
-void rb_include_module(VALUE,VALUE);
-void rb_extend_object(VALUE,VALUE);
-void rb_prepend_module(VALUE,VALUE);
+/** @} */
RBIMPL_SYMBOL_EXPORT_END()