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

From ba814a5aa3c69322d616471e934592b261448645 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: Mon, 7 Jun 2021 17:26:34 +0900
Subject: include/ruby/backward/2/assume.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/backward/2/assume.h | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/include/ruby/backward/2/assume.h b/include/ruby/backward/2/assume.h
index 73a247d..265421d 100644
--- a/include/ruby/backward/2/assume.h
+++ b/include/ruby/backward/2/assume.h
@@ -26,15 +26,30 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/backward/2/assume.h#L26
 
 #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)
-- 
cgit v1.1


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