ruby-changes:67721
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:00:59 +0900 (JST)
Subject: [ruby-changes:67721] 1f66d8a77b (master): include/ruby/internal/newobj.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=1f66d8a77b From 1f66d8a77b4d7efcff778ba82284b7b651b53104 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, 18 Jan 2021 12:27:20 +0900 Subject: include/ruby/internal/newobj.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- class.c | 4 -- include/ruby/internal/newobj.h | 150 ++++++++++++++++++++++++++++++++++++++--- object.c | 8 --- 3 files changed, 140 insertions(+), 22 deletions(-) diff --git a/class.c b/class.c index b7247e7..b25e961 100644 --- a/class.c +++ b/class.c @@ -536,10 +536,6 @@ rb_singleton_class_clone_and_attach(VALUE obj, VALUE attach) https://github.com/ruby/ruby/blob/trunk/class.c#L536 } } -/*! - * Attach a object to a singleton class. - * @pre \a klass is the singleton class of \a obj. - */ void rb_singleton_class_attached(VALUE klass, VALUE obj) { diff --git a/include/ruby/internal/newobj.h b/include/ruby/internal/newobj.h index e807b99..a8a5557 100644 --- a/include/ruby/internal/newobj.h +++ b/include/ruby/internal/newobj.h @@ -29,26 +29,146 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/newobj.h#L29 #include "ruby/internal/value.h" #include "ruby/assert.h" +/** + * Declares, allocates, then assigns a new object to the given variable. + * + * @param obj Variable name. + * @param type Variable type. + * @exception rb_eNoMemError No space left. + * @return An allocated object, not initialised. + * @note Modern programs tend to use #NEWOBJ_OF instead. + * + * @internal + * + * :FIXME: Should we deprecate it? + */ #define RB_NEWOBJ(obj,type) type *(obj) = RBIMPL_CAST((type *)rb_newobj()) + +/** + * Identical to #RB_NEWOBJ, except it also accepts the allocating object's + * class and flags. + * + * @param obj Variable name. + * @param type Variable type. + * @param klass Object's class. + * @param flags Object's flags. + * @exception rb_eNoMemError No space left. + * @return An allocated object, filled with the arguments. + */ #define RB_NEWOBJ_OF(obj,type,klass,flags) type *(obj) = RBIMPL_CAST((type *)rb_newobj_of(klass, flags)) -#define NEWOBJ RB_NEWOBJ -#define NEWOBJ_OF RB_NEWOBJ_OF /* core has special NEWOBJ_OF() in internal.h */ -#define OBJSETUP rb_obj_setup /* use NEWOBJ_OF instead of NEWOBJ()+OBJSETUP() */ -#define CLONESETUP rb_clone_setup -#define DUPSETUP rb_dup_setup +#define NEWOBJ RB_NEWOBJ /**< @old{RB_NEWOBJ} */ +#define NEWOBJ_OF RB_NEWOBJ_OF /**< @old{RB_NEWOBJ_OF} */ +#define OBJSETUP rb_obj_setup /**< @old{rb_obj_setup} */ +#define CLONESETUP rb_clone_setup /**< @old{rb_clone_setup} */ +#define DUPSETUP rb_dup_setup /**< @old{rb_dup_setup} */ RBIMPL_SYMBOL_EXPORT_BEGIN() +/** + * This is the implementation detail of #RB_NEWOBJ. + * + * @exception rb_eNoMemError No space left. + * @return An allocated object, not initialised. + */ VALUE rb_newobj(void); -VALUE rb_newobj_of(VALUE, VALUE); + +/** + * This is the implementation detail of #RB_NEWOBJ_OF. + * + * @param klass Object's class. + * @param flags Object's flags. + * @exception rb_eNoMemError No space left. + * @return An allocated object, filled with the arguments. + */ +VALUE rb_newobj_of(VALUE klass, VALUE flags); + +/** + * Fills common fields in the object. + * + * @note Prefer rb_newobj_of() to this function. + * @param[in,out] obj A Ruby object to be set up. + * @param[in] klass `obj` will belong to this class. + * @param[in] type One of ::ruby_value_type. + * @return The passed object. + * + * @internal + * + * Historically, authors of Ruby has described the `type` argument as "one of + * ::ruby_value_type". In reality it accepts either ::ruby_value_type, + * ::ruby_fl_type, or any combinations of the two. For instance + * `RUBY_T_STRING | RUBY_FL_FREEZE` is a valid value that this function takes, + * and means this is a frozen string. + * + * 3rd party extension libraries rarely need to allocate Strings this way. + * They normally only concern ::RUBY_T_DATA. This argument is mainly used for + * specifying flags, @shyouhei suspects. + */ VALUE rb_obj_setup(VALUE obj, VALUE klass, VALUE type); -VALUE rb_obj_class(VALUE); -VALUE rb_singleton_class_clone(VALUE); -void rb_singleton_class_attached(VALUE,VALUE); -void rb_copy_generic_ivar(VALUE,VALUE); + +/** + * Queries the class of an object. This is not always identical to + * `RBASIC_CLASS(obj)`. It searches for the nearest ancestor skipping + * singleton classes or included modules. + * + * @param[in] obj Object in question. + * @return The object's class, in a normal sense. + */ +VALUE rb_obj_class(VALUE obj); + +/** + * Clones a singleton class. An object can have its own singleton class. OK. + * Then what happens when a program clones such object? The singleton class + * that is attached to the source object must also be cloned. Otherwise a + * singleton object gets shared with two objects, which breaks "singleton"-ness + * of such class. + * + * This is basically an implementation detail of rb_clone_setup(). People + * need not be aware of this working behind-the-scene. + * + * @param[in] obj The object that has its own singleton class. + * @return Cloned singleton class. + */ +VALUE rb_singleton_class_clone(VALUE obj); + +/** + * Attaches a singleton class to its corresponding object. + * + * This is basically an implementation detail of rb_clone_setup(). People + * need not be aware of this working behind-the-scene. + * + * @param[in] klass The singleton class. + * @param[out] obj The object to attach a class. + * @pre The passed two objects must agree with each other that `klass` + * becomes a singleton class of `obj`. + * @post `klass` becomes the singleton class of `obj`. + */ +void rb_singleton_class_attached(VALUE klass, VALUE obj); + +/** + * Copies the list of instance variables. 3rd parties need not know, but there + * are several ways to store an object's instance variables, depending on its + * internal structure. This function makes sense when either of the passed + * objects are using so-called "generic" backend storage. This distinction is + * purely an implementation detail of rb_clone_setup(). People need not be + * aware of this working behind-the-scenes. + * + * @param[out] clone The destination object. + * @param[in] obj The source object. + */ +void rb_copy_generic_ivar(VALUE clone, VALUE obj); RBIMPL_SYMBOL_EXPORT_END() RBIMPL_ATTR_DEPRECATED(("This is no longer how Object#clone works.")) +/** + * @deprecated Not sure exactly when but at some time, the implementation of + * `Object#clone` stopped using this function. It remained + * untouched for a while, and then @shyouhei realised that they + * are no longer doing the same thing. It seems nobody seriously + * uses this function any longer. Let's just abandon it. + * + * @param[out] clone The destination object. + * @param[in] obj The source object. + */ static inline void rb_clone_setup(VALUE clone, VALUE obj) { @@ -56,6 +176,16 @@ rb_clone_setup(VALUE clone, VALUE obj) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/newobj.h#L176 } RBIMPL_ATTR_DEPRECATED(("This is no longer how Object#dup works.")) +/** + * @deprecated Not sure exactly when but at some time, the implementation of + * `Object#dup` stopped using this function. It remained + * untouched for a while, and then @shyouhei realised that they + * are no longer the same thing. It seems nobody seriously uses + * this function any longer. Let's just abandon it. + * + * @param[out] dup The destination object. + * @param[in] obj The source object. + */ static inline void rb_dup_setup(VALUE dup, VALUE obj) { diff --git a/object.c b/object.c index 31633f9..9952550 100644 --- a/object.c +++ b/object.c @@ -115,14 +115,6 @@ rb_obj_reveal(VALUE obj, VALUE klass) https://github.com/ruby/ruby/blob/trunk/object.c#L115 return obj; } -/*! - * Fills common (\c RBasic) fields in \a obj. - * - * \note Prefer rb_newobj_of() to this function. - * \param[in,out] obj a Ruby object to be set up. - * \param[in] klass \c obj will belong to this class. - * \param[in] type one of \c ruby_value_type - */ VALUE rb_obj_setup(VALUE obj, VALUE klass, VALUE type) { -- cgit v1.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/