https://git.ruby-lang.org/ruby.git/commit/?id=7c28330ca0

From 7c28330ca03d124068f608e9d8d1a4e07ba5dd7d 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: Tue, 2 Feb 2021 16:34:14 +0900
Subject: include/ruby/internal/core/rclass.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/core/rclass.h | 97 ++++++++++++++++++++++++++++++++++++-
 object.c                            |  7 ---
 2 files changed, 95 insertions(+), 9 deletions(-)

diff --git a/include/ruby/internal/core/rclass.h b/include/ruby/internal/core/rclass.h
index 2e4288f..13a33a2 100644
--- a/include/ruby/internal/core/rclass.h
+++ b/include/ruby/internal/core/rclass.h
@@ -18,30 +18,123 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/core/rclass.h#L18
  *             Do not  expect for  instance `__VA_ARGS__` is  always available.
  *             We assume C99  for ruby itself but we don't  assume languages of
  *             extension libraries.  They could be written in C++98.
- * @brief      Routines to manipulate struct ::RClass.
+ * @brief      Routines to manipulate struct RClass.
+ * @note       The struct RClass itself is opaque.
  */
 #include "ruby/internal/dllexport.h"
 #include "ruby/internal/value.h"
 #include "ruby/internal/cast.h"
 
+/** @cond INTERNAL_MACRO */
 #define RMODULE_IS_OVERLAID              RMODULE_IS_OVERLAID
 #define RMODULE_IS_REFINEMENT            RMODULE_IS_REFINEMENT
 #define RMODULE_INCLUDED_INTO_REFINEMENT RMODULE_INCLUDED_INTO_REFINEMENT
+/** @endcond */
 
+/**
+ * Convenient casting macro.
+ *
+ * @param   obj  An object, which is in fact an RClass.
+ * @return  The passed object casted to RClass.
+ */
 #define RCLASS(obj)  RBIMPL_CAST((struct RClass *)(obj))
+
+/** @alias{RCLASS} */
 #define RMODULE      RCLASS
+
+/** @alias{rb_class_get_superclass} */
 #define RCLASS_SUPER rb_class_get_superclass
 
+/**
+ * @private
+ *
+ * Bits that you can set to ::RBasic::flags.
+ *
+ * @internal
+ *
+ * Why is it here, given RClass itself is not?
+ */
 enum ruby_rmodule_flags {
+
+    /**
+     * This flag has something to do with refinements... I guess?  It is set on
+     * occasions  for modules  that are  refined by  refinements, but  it seems
+     * ...  nobody cares  about  such things?   Not sure  but  this flag  could
+     * perhaps be a write-only information.
+     */
     RMODULE_IS_OVERLAID              = RUBY_FL_USER2,
+
+    /**
+     * This flag has something to do  with refinements.  A module created using
+     * rb_mod_refine()  has this  flag set.   This  is the  bit which  controls
+     * difference between normal inclusion versus refinements.
+     */
     RMODULE_IS_REFINEMENT            = RUBY_FL_USER3,
+
+    /**
+     * This flag  has something  to do  with refinements.  This  is set  when a
+     * (non-refinement)  module is  included into  another module,  which is  a
+     * refinement.  This amends the way `super` searches for a super method.
+     *
+     * ```ruby
+     * class Foo
+     *   def foo
+     *     "Foo"
+     *   end
+     * end
+     *
+     * module Bar
+     *   def foo
+     *     "[#{super}]" # this
+     *   end
+     * end
+     *
+     * module Baz
+     *   refine Foo do
+     *     include Bar
+     *     def foo
+     *       "<#{super}>"
+     *     end
+     *   end
+     * end
+     *
+     * using Baz
+     * Foo.new.foo # => "[<Foo>]"
+     * ```
+     *
+     * The  `super`  marked  with  "this"   comment  shall  look  for  overlaid
+     * `Foo#foo`, which is not the ordinal method lookup direction.
+     */
     RMODULE_INCLUDED_INTO_REFINEMENT = RUBY_FL_USER4
 };
 
 struct RClass; /* Opaque, declared here for RCLASS() macro. */
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
-VALUE rb_class_get_superclass(VALUE);
+/**
+ * Returns the superclass of a class.
+ * @param[in]  klass        An object of RClass.
+ * @retval     RUBY_Qfalse  `klass` has no super class.
+ * @retval     otherwise    Raw superclass of `klass`
+ * @see        rb_class_superclass
+ *
+ * ### Q&A ###
+ *
+ * - Q: How can a class have no super class?
+ *
+ * - A: `klass` could be a module.  Or it could be ::rb_cBasicObject.
+ *
+ * - Q: What do you mean by "raw" superclass?
+ *
+ * - A: This  is a  really good  question.  The  answer is  that this  function
+ *      returns something  different from what  you would normally  expect.  On
+ *      occasions  ruby  inserts  hidden  classes   in  a  hierarchy  of  class
+ *      inheritance behind-the-scene.   Such classes are called  "iclass"es and
+ *      distinguished  using  ::RUBY_T_ICLASS  in  C  level.   They  are  truly
+ *      transparent from Ruby  level but can be accessed from  C, by using this
+ *      API.
+ */
+VALUE rb_class_get_superclass(VALUE klass);
 RBIMPL_SYMBOL_EXPORT_END()
 
 #endif /* RBIMPL_RCLASS_H */
diff --git a/object.c b/object.c
index 6631e99..6dc3a8e 100644
--- a/object.c
+++ b/object.c
@@ -2192,13 +2192,6 @@ rb_class_superclass(VALUE klass) https://github.com/ruby/ruby/blob/trunk/object.c#L2192
     return super;
 }
 
-/**
- * Returns the superclass of \a klass
- * The return value might be an iclass of a module, unlike rb_class_superclass.
- *
- * Also it returns Qfalse when \a klass does not have a parent class.
- * \sa rb_class_superclass
- */
 VALUE
 rb_class_get_superclass(VALUE klass)
 {
-- 
cgit v1.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/