summaryloggraphiclog1graphiclog2commitcommitdifftreerefseditfork
rawpatchinlineside by side (parent: 9c4aa94)
rawpatchinlineside by side (parent: 9c4aa94)
| author | 卜部昌平 <[email protected]> | |
| Wed, 3 Feb 2021 02:27:49 +0000 (3 11:27 +0900) | ||
| committer | 卜部昌平 <[email protected]> | |
| Fri, 10 Sep 2021 11:00:06 +0000 (10 20:00 +0900) |
Must not be a bad idea to improve documents. [ci skip]
| include/ruby/internal/core/rbasic.h | patchblobblamehistory | |
| object.c | patchblobblamehistory |
#include "ruby/internal/value.h"
#include "ruby/assert.h"
-#define RBASIC(obj) RBIMPL_CAST((struct RBasic *)(obj))
-#define RBASIC_CLASS RBASIC_CLASS
-#define RVALUE_EMBED_LEN_MAX RVALUE_EMBED_LEN_MAX
-
+/**
+ * Convenient casting macro.
+ *
+ * @param obj Arbitrary Ruby object.
+ * @return The passed object casted to ::RBasic.
+ */
+#define RBASIC(obj) RBIMPL_CAST((struct RBasic *)(obj))
/** @cond INTERNAL_MACRO */
+#define RBASIC_CLASS RBASIC_CLASS
+#define RBIMPL_RVALUE_EMBED_LEN_MAX 3
+#define RVALUE_EMBED_LEN_MAX RVALUE_EMBED_LEN_MAX
#define RBIMPL_EMBED_LEN_MAX_OF(T) \
RBIMPL_CAST((int)(sizeof(VALUE[RBIMPL_RVALUE_EMBED_LEN_MAX]) / (sizeof(T))))
/** @endcond */
-#define RBIMPL_RVALUE_EMBED_LEN_MAX 3
-enum ruby_rvalue_flags { RVALUE_EMBED_LEN_MAX = RBIMPL_RVALUE_EMBED_LEN_MAX };
+/**
+ * This is an enum because GDB wants it (rather than a macro). People need not
+ * bother.
+ */
+enum ruby_rvalue_flags {
+ /** Max possible number of objects that can be embedded. */
+ RVALUE_EMBED_LEN_MAX = RBIMPL_RVALUE_EMBED_LEN_MAX
+};
+/**
+ * Ruby's object's, base components. Every single ruby objects have them in
+ * common.
+ */
struct
RUBY_ALIGNAS(SIZEOF_VALUE)
RBasic {
- VALUE flags; /**< @see enum ::ruby_fl_type. */
+
+ /**
+ * Per-object flags. Each ruby objects have their own characteristics
+ * apart from their classes. For instance whether an object is frozen or
+ * not is not controlled by its class. This is where such properties are
+ * stored.
+ *
+ * @see enum ::ruby_fl_type
+ *
+ * @note This is ::VALUE rather than an enum for alignment purpose. Back
+ * in the 1990s there were no such thing like `_Alignas` in C.
+ */
+ VALUE flags;
+
+ /**
+ * Class of an object. Every object has its class. Also, everything is an
+ * object in Ruby. This means classes are also objects. Classes have
+ * their own classes, classes of classes have their classes, too ... and
+ * it recursively continues forever.
+ *
+ * Also note the `const` qualifier. In ruby an object cannot "change" its
+ * class.
+ */
const VALUE klass;
#ifdef __cplusplus
};
RBIMPL_SYMBOL_EXPORT_BEGIN()
+/**
+ * Make the object invisible from Ruby code.
+ *
+ * It is useful to let Ruby's GC manage your internal data structure -- The
+ * object keeps being managed by GC, but `ObjectSpace.each_object` never yields
+ * the object.
+ *
+ * Note that the object also lose a way to call a method on it.
+ *
+ * @param[out] obj A Ruby object.
+ * @return The passed object.
+ * @post The object is destructively modified to be invisible.
+ * @see rb_obj_reveal
+ */
VALUE rb_obj_hide(VALUE obj);
+
+/**
+ * Make a hidden object visible again.
+ *
+ * It is the caller's responsibility to pass the right `klass` which `obj`
+ * originally used to belong to.
+ *
+ * @param[out] obj A Ruby object.
+ * @param[in] klass Class of `obj`.
+ * @return Passed `obj`.
+ * @pre `obj` was previously hidden.
+ * @post `obj`'s class is `klass`.
+ * @see rb_obj_hide
+ */
VALUE rb_obj_reveal(VALUE obj, VALUE klass); /* do not use this API to change klass information */
RBIMPL_SYMBOL_EXPORT_END()
RBIMPL_ATTR_PURE_UNLESS_DEBUG()
RBIMPL_ATTR_ARTIFICIAL()
+/**
+ * Queries the class of an object.
+ *
+ * @param[in] obj An object.
+ * @return Its class.
+ */
static inline VALUE
RBASIC_CLASS(VALUE obj)
{
diff --git a/object.c b/object.c
--- a/object.c
+++ b/object.c
/*! \endcond */
-/*!
- * Make the object invisible from Ruby code.
- *
- * It is useful to let Ruby's GC manage your internal data structure --
- * The object keeps being managed by GC, but \c ObjectSpace.each_object
- * never yields the object.
- *
- * Note that the object also lose a way to call a method on it.
- *
- * \param[in] obj a Ruby object
- * \sa rb_obj_reveal
- */
VALUE
rb_obj_hide(VALUE obj)
{
return obj;
}
-/*!
- * Make a hidden object visible again.
- *
- * It is the caller's responsibility to pass the right \a klass
- * which \a obj originally used to belong to.
- *
- * \sa rb_obj_hide
- */
VALUE
rb_obj_reveal(VALUE obj, VALUE klass)
{