1 files changed, 34 insertions, 5 deletions
diff --git a/include/ruby/internal/core/rbignum.h b/include/ruby/internal/core/rbignum.h
index 89db566501..1d31743235 100644
--- a/include/ruby/internal/core/rbignum.h
+++ b/include/ruby/internal/core/rbignum.h
@@ -17,15 +17,16 @@
  *             recursively included  from extension  libraries written  in C++.
  *             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.
+ *             extension libraries.  They could be written in C++98.
+ * @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,17 +34,45 @@
 /** @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) {
+RBIGNUM_POSITIVE_P(VALUE b)
+{
     RBIMPL_ASSERT_TYPE(b, RUBY_T_BIGNUM);
     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) {
+RBIGNUM_NEGATIVE_P(VALUE b)
+{
     RBIMPL_ASSERT_TYPE(b, RUBY_T_BIGNUM);
     return ! RBIGNUM_POSITIVE_P(b);
 }