include/ruby/backward/2/assume.h: add doxygen

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

1 files changed, 19 insertions, 4 deletions

diff --git a/include/ruby/backward/2/assume.h b/include/ruby/backward/2/assume.h
index 73a247d48e..265421df79 100644
--- a/include/ruby/backward/2/assume.h
+++ b/include/ruby/backward/2/assume.h
@@ -26,15 +26,30 @@
 
 #undef  ASSUME             /* Kill config.h definition */
 #undef  UNREACHABLE        /* Kill config.h definition */
-#define ASSUME             RBIMPL_ASSUME
-#define UNREACHABLE        RBIMPL_UNREACHABLE()
-#define UNREACHABLE_RETURN RBIMPL_UNREACHABLE_RETURN
+#define ASSUME             RBIMPL_ASSUME             /**< @old{RBIMPL_ASSUME} */
+#define UNREACHABLE        RBIMPL_UNREACHABLE()      /**< @old{RBIMPL_UNREACHABLE} */
+#define UNREACHABLE_RETURN RBIMPL_UNREACHABLE_RETURN /**< @old{RBIMPL_UNREACHABLE_RETURN} */
 
 /* likely */
 #if RBIMPL_HAS_BUILTIN(__builtin_expect)
+/**
+ * Asserts that the given Boolean expression likely holds.
+ *
+ * @param  x  An expression that likely holds.
+ *
+ * @note  Consider this macro carefully.  It has been here since when CPUs were
+ *        like  babies,  but  contemporary  processors are  beasts.   They  are
+ *        smarter than  mare mortals like  us today.  Their  branch predictions
+ *        highly expectedly outperform your use of this macro.
+ */
 # define RB_LIKELY(x)   (__builtin_expect(!!(x), 1))
-# define RB_UNLIKELY(x) (__builtin_expect(!!(x), 0))
 
+/**
+ * Asserts that the given Boolean expression likely doesn't hold.
+ *
+ * @param  x  An expression that likely doesn't hold.
+ */
+# define RB_UNLIKELY(x) (__builtin_expect(!!(x), 0))
 #else
 # define RB_LIKELY(x)   (x)
 # define RB_UNLIKELY(x) (x)