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

Must not be a bad idea to improve documents. [ci skip]

3 files changed, 140 insertions, 22 deletions

diff --git a/class.c b/class.c
index b7247e7489..b25e961b27 100644
--- a/class.c
+++ b/class.c
@@ -536,10 +536,6 @@ rb_singleton_class_clone_and_attach(VALUE obj, VALUE attach)
     }
 }
 
-/*!
- * 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 e807b99043..a8a5557a25 100644
--- a/include/ruby/internal/newobj.h
+++ b/include/ruby/internal/newobj.h
@@ -29,26 +29,146 @@
 #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)
 }
 
 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 31633f91db..99525504a4 100644
--- a/object.c
+++ b/object.c
@@ -115,14 +115,6 @@ rb_obj_reveal(VALUE obj, VALUE klass)
     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)
 {