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

@@ -30,7 +30,7 @@
 #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 @@
 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)
     return RB_LONG2FIX(y);
 }
 
-#endif /* RBIMPL_ARITHMERIC_ST_DATA_T_H */
+#endif /* RBIMPL_ARITHMETIC_ST_DATA_T_H */