include/ruby/internal/arithmetic/double.h: add doxygen

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

1 files changed, 40 insertions, 7 deletions

diff --git a/include/ruby/internal/arithmetic/double.h b/include/ruby/internal/arithmetic/double.h
index 79c98915ba..229de47aef 100644
--- a/include/ruby/internal/arithmetic/double.h
+++ b/include/ruby/internal/arithmetic/double.h
@@ -24,16 +24,49 @@
 #include "ruby/internal/dllexport.h"
 #include "ruby/internal/value.h"
 
-#define NUM2DBL      rb_num2dbl
-#define RFLOAT_VALUE rb_float_value
-#define DBL2NUM      rb_float_new
+#define NUM2DBL      rb_num2dbl       /**< @old{rb_num2dbl} */
+#define RFLOAT_VALUE rb_float_value   /**< @old{rb_float_value} */
+#define DBL2NUM      rb_float_new     /**< @old{rb_float_new} */
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
-double rb_num2dbl(VALUE);
+/**
+ * Converts an instance of ::rb_cNumeric into C's `double`.
+ *
+ * @param[in]  num             Something numeric.
+ * @exception  rb_eTypeError   `num` is not a numeric.
+ * @return     The passed value converted into C's `double`.
+ */
+double rb_num2dbl(VALUE num);
+
 RBIMPL_ATTR_PURE()
-double rb_float_value(VALUE);
-VALUE rb_float_new(double);
-VALUE rb_float_new_in_heap(double);
+/**
+ * Extracts its double value from an instance of ::rb_cFloat.
+ *
+ * @param[in]  num  An instance of ::rb_cFloat.
+ * @pre        Must not pass anything other than a Fixnum.
+ * @return     The passed value converted into C's `double`.
+ */
+double rb_float_value(VALUE num);
+
+/**
+ * Converts a C's `double` into an instance of ::rb_cFloat.
+ *
+ * @param[in]  d  Arbitrary `double` value.
+ * @return     An instance of ::rb_cFloat.
+ */
+VALUE rb_float_new(double d);
+
+/**
+ * Identical to rb_float_new(), except it does not generate Flonums.
+ *
+ * @param[in]  d  Arbitrary `double` value.
+ * @return     An instance of ::rb_cFloat.
+ *
+ * @internal
+ *
+ * @shyouhei has no idea why it is here.
+ */
+VALUE rb_float_new_in_heap(double d);
 RBIMPL_SYMBOL_EXPORT_END()
 
 #endif /* RBIMPL_ARITHMETIC_DOUBLE_H */