ruby-changes:67728
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:01:05 +0900 (JST)
Subject: [ruby-changes:67728] 9ba9dbf168 (master): include/ruby/internal/module.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=9ba9dbf168 From 9ba9dbf168c8be042a11baad90a2b7bf8428a478 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?= <shyouhei@r...> Date: Mon, 21 Dec 2020 16:32:40 +0900 Subject: 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. --- class.c | 52 +------------- eval.c | 6 -- include/ruby/internal/module.h | 152 ++++++++++++++++++++++++++++++++++++++--- 3 files changed, 144 insertions(+), 66 deletions(-) diff --git a/class.c b/class.c index b25e961..35f9b86 100644 --- a/class.c +++ b/class.c @@ -10,16 +10,7 @@ https://github.com/ruby/ruby/blob/trunk/class.c#L10 **********************************************************************/ /*! - * \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) https://github.com/ruby/ruby/blob/trunk/class.c#L725 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) https://github.com/ruby/ruby/blob/trunk/class.c#L757 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) https://github.com/ruby/ruby/blob/trunk/class.c#L832 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) https://github.com/ruby/ruby/blob/trunk/class.c#L856 return module; } -/*! - * \note the compaction GC does not move modules returned by this function. - */ VALUE rb_define_module_under(VALUE outer, const char *name) { diff --git a/eval.c b/eval.c index 885e1ae..ef98d71 100644 --- a/eval.c +++ b/eval.c @@ -1713,12 +1713,6 @@ rb_obj_call_init_kw(VALUE obj, int argc, const VALUE *argv, int kw_splat) https://github.com/ruby/ruby/blob/trunk/eval.c#L1713 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) { diff --git a/include/ruby/internal/module.h b/include/ruby/internal/module.h index f32e0b9..d678dd2 100644 --- a/include/ruby/internal/module.h +++ b/include/ruby/internal/module.h @@ -23,20 +23,154 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/module.h#L23 #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 (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/