include/ruby/internal/core/rbignum.h: add doxgen

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

1 files changed, 29 insertions, 2 deletions

diff --git a/include/ruby/internal/core/rbignum.h b/include/ruby/internal/core/rbignum.h
index 1b9126d515..1d31743235 100644
--- a/include/ruby/internal/core/rbignum.h
+++ b/include/ruby/internal/core/rbignum.h
@@ -18,14 +18,15 @@
  *             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 ::RBignum.
+ * @brief      Routines to manipulate struct RBignum.
+ * @note       The struct RBignum itself is opaque.
  */
 #include "ruby/internal/dllexport.h"
 #include "ruby/internal/value.h"
 #include "ruby/internal/value_type.h"
 #include "ruby/internal/stdbool.h"
 
-#define RBIGNUM_SIGN rb_big_sign
+#define RBIGNUM_SIGN rb_big_sign /**< @alias{rb_big_sign} */
 
 /** @cond INTERNAL_MACRO */
 #define RBIGNUM_POSITIVE_P RBIGNUM_POSITIVE_P
@@ -33,9 +34,29 @@
 /** @endcond */
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
+/**
+ * The "sign" of a bignum.
+ *
+ * @param[in]  num  An object of RBignum.
+ * @retval     1    It is greater than or equal to zero.
+ * @retval     0    It is less than zero.
+ *
+ * @internal
+ *
+ * Implementation wise, unlike fixnums (which  are 2's complement), bignums are
+ * signed  magnitude  system.   Theoretically  it could  be  possible  to  have
+ * negative zero  instances.  But  in reality  there is no  way to  create such
+ * thing.  Nobody ever needed that kind of insanity.
+ */
 int rb_big_sign(VALUE num);
 RBIMPL_SYMBOL_EXPORT_END()
 
+/**
+ * Checks if the bignum is positive.
+ * @param[in]  b      An object of RBignum.
+ * @retval     false  `b` is less than zero.
+ * @retval     true   Otherwise.
+ */
 static inline bool
 RBIGNUM_POSITIVE_P(VALUE b)
 {
@@ -43,6 +64,12 @@ RBIGNUM_POSITIVE_P(VALUE b)
     return RBIGNUM_SIGN(b);
 }
 
+/**
+ * Checks if the bignum is negative.
+ * @param[in]  b      An object of RBignum.
+ * @retval     true   `b` is less than zero.
+ * @retval     false  Otherwise.
+ */
 static inline bool
 RBIGNUM_NEGATIVE_P(VALUE b)
 {