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

From 86d4fe686c52920c2bb638fd1da731e811c4261a 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: Thu, 21 Jan 2021 11:57:07 +0900
Subject: include/ruby/internal/arithmetic/st_data_t.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/arithmetic/st_data_t.h | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/include/ruby/internal/arithmetic/st_data_t.h b/include/ruby/internal/arithmetic/st_data_t.h
index 867c382..3bff4ff 100644
--- a/include/ruby/internal/arithmetic/st_data_t.h
+++ b/include/ruby/internal/arithmetic/st_data_t.h
@@ -30,7 +30,7 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/st_data_t.h#L30
 #include "ruby/assert.h"
 #include "ruby/st.h"
 
-#define ST2FIX    RB_ST2FIX
+#define ST2FIX    RB_ST2FIX     /**< @old{RB_ST2FIX} */
 /** @cond INTERNAL_MACRO */
 #define RB_ST2FIX RB_ST2FIX
 /** @endcond */
@@ -38,7 +38,23 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/st_data_t.h#L38
 RBIMPL_ATTR_CONST_UNLESS_DEBUG()
 RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14)
 RBIMPL_ATTR_ARTIFICIAL()
-/* See also [ruby-core:84395] [Bug #14218] [ruby-core:82687] [Bug #13877] */
+/**
+ * Converts a C's `st_data_t` into an instance of ::rb_cInteger.
+ *
+ * @param[in]  i  The data in question.
+ * @return     A converted result
+ * @warning    THIS CONVERSION LOSES DATA!  Be warned.
+ * @see        https://bugs.ruby-lang.org/issues/13877
+ * @see        https://bugs.ruby-lang.org/issues/14218
+ *
+ * @internal
+ *
+ * This  is   needed  because  of   hash  functions.   Hash   functions  return
+ * `st_data_t`,  which could  theoretically  be bigger  than Fixnums.   However
+ * allocating Bignums for them every time  we calculate hash values is just too
+ * heavy.  To avoid  penalty we need to  ignore some upper bit(s)  and stick to
+ * Fixnums.  This function is used for that purpose.
+ */
 static inline VALUE
 RB_ST2FIX(st_data_t i)
 {
@@ -56,4 +72,4 @@ RB_ST2FIX(st_data_t i) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/st_data_t.h#L72
     return RB_LONG2FIX(y);
 }
 
-#endif /* RBIMPL_ARITHMERIC_ST_DATA_T_H */
+#endif /* RBIMPL_ARITHMETIC_ST_DATA_T_H */
-- 
cgit v1.1


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