include/ruby/internal/core/robject.h: add doxygen

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

include/ruby/internal/core/robject.h

@@ -34,35 +34,113 @@
 #include "ruby/internal/value.h"
 #include "ruby/internal/value_type.h"
 
+/**
+ * Convenient casting macro.
+ *
+ * @param   obj  An object, which is in fact an ::RRegexp.
+ * @return  The passed object casted to ::RRegexp.
+ */
 #define ROBJECT(obj)          RBIMPL_CAST((struct RObject *)(obj))
+/** @cond INTERNAL_MACRO */
 #define ROBJECT_EMBED_LEN_MAX ROBJECT_EMBED_LEN_MAX
 #define ROBJECT_EMBED         ROBJECT_EMBED
-/** @cond INTERNAL_MACRO */
 #define ROBJECT_NUMIV         ROBJECT_NUMIV
 #define ROBJECT_IVPTR         ROBJECT_IVPTR
 #define ROBJECT_IV_INDEX_TBL  ROBJECT_IV_INDEX_TBL
 /** @endcond */
 
-enum ruby_robject_flags { ROBJECT_EMBED = RUBY_FL_USER1 };
+/**
+ * @private
+ *
+ * Bits that you can set to ::RBasic::flags.
+ */
+enum ruby_robject_flags {
+    /**
+     * This flag has  something to do with memory footprint.   If the object is
+     * "small"  enough, ruby  tries to  be creative  to abuse  padding bits  of
+     * struct ::RObject for storing instance variables.  This flag denotes that
+     * situation.
+     *
+     * @warning  This  bit has  to be  considered read-only.   Setting/clearing
+     *           this  bit without  corresponding fix  up must  cause immediate
+     *           SEGV.   Also,   internal  structures   of  an   object  change
+     *           dynamically  and  transparently  throughout of  its  lifetime.
+     *           Don't assume it being persistent.
+     *
+     * @internal
+     *
+     * 3rd parties must  not be aware that  there even is more than  one way to
+     * store instance variables.  Might better be hidden.
+     */
+    ROBJECT_EMBED = RUBY_FL_USER1
+};
 
-enum ruby_robject_consts { ROBJECT_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(VALUE) };
+/**
+ * This is an enum because GDB wants it (rather than a macro).  People need not
+ * bother.
+ */
+enum ruby_robject_consts {
+    /** Max possible number of instance variables that can be embedded. */
+    ROBJECT_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(VALUE)
+};
 
 struct st_table;
 
+/**
+ * Ruby's ordinal objects.  Unless otherwise  special cased, all predefined and
+ * user-defined classes share this struct to hold their instances.
+ */
 struct RObject {
+
+    /** Basic part, including flags and class. */
     struct RBasic basic;
+
+    /** Object's specific fields. */
     union {
+
+        /**
+         * Object that use  separated memory region for  instance variables use
+         * this pattern.
+         */
         struct {
+
+            /**
+             * Number of instance variables.  This is per object; objects might
+             * differ in this field even if they have the identical classes.
+             */
             uint32_t numiv;
+
+            /** Pointer to a C array that holds instance variables. */
             VALUE *ivptr;
-            struct st_table *iv_index_tbl; /* shortcut for RCLASS_IV_INDEX_TBL(rb_obj_class(obj)) */
+
+            /**
+             * This  is a  table that  holds  instance variable  name to  index
+             * mapping.  Used when accessing instance variables using names.
+             *
+             * @internal
+             *
+             * This is a shortcut for `RCLASS_IV_INDEX_TBL(rb_obj_class(obj))`.
+             */
+            struct st_table *iv_index_tbl;
         } heap;
+
+        /**
+         * Embedded instance  variables.  When  an object  is small  enough, it
+         * uses this area to store the instance variables.
+         */
         VALUE ary[ROBJECT_EMBED_LEN_MAX];
     } as;
 };
 
 RBIMPL_ATTR_PURE_UNLESS_DEBUG()
 RBIMPL_ATTR_ARTIFICIAL()
+/**
+ * Queries the number of instance variables.
+ *
+ * @param[in]  obj  Object in question.
+ * @return     Its number of instance variables.
+ * @pre        `obj` must be an instance of ::RObject.
+ */
 static inline uint32_t
 ROBJECT_NUMIV(VALUE obj)
 {
@@ -78,6 +156,17 @@ ROBJECT_NUMIV(VALUE obj)
 
 RBIMPL_ATTR_PURE_UNLESS_DEBUG()
 RBIMPL_ATTR_ARTIFICIAL()
+/**
+ * Queries the instance variables.
+ *
+ * @param[in]  obj  Object in question.
+ * @return     Its instance variables, in C array.
+ * @pre        `obj` must be an instance of ::RObject.
+ *
+ * @internal
+ *
+ * @shyouhei finds no reason for this to be visible from extension libraries.
+ */
 static inline VALUE *
 ROBJECT_IVPTR(VALUE obj)
 {