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

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

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 NUM2DBL      rb_num2dbl       /**< @old{rb_num2dbl} */
-#define RFLOAT_VALUE rb_float_value
+#define RFLOAT_VALUE rb_float_value   /**< @old{rb_float_value} */
-#define DBL2NUM      rb_float_new
+#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);
+ * Extracts its double value from an instance of ::rb_cFloat.
-VALUE rb_float_new_in_heap(double);
+ *
+ * @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 */

object.c

@@ -3624,13 +3624,6 @@ rb_num_to_dbl(VALUE val)
     return RFLOAT_VALUE(val);
 }
 
-/*!
- * Converts a \c Numeric object to \c double.
- * \param[in] val a \c Numeric object
- * \return the converted value
- * \exception TypeError if \a val is not a \c Numeric or
- *   it does not support conversion to a floating point number.
- */
 double
 rb_num2dbl(VALUE val)
 {