include/ruby/internal/intern/compar.h: add doxygen

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

1 files changed, 30 insertions, 2 deletions

diff --git a/include/ruby/internal/intern/compar.h b/include/ruby/internal/intern/compar.h
index ede86267a2..dc3b377b01 100644
--- a/include/ruby/internal/intern/compar.h
+++ b/include/ruby/internal/intern/compar.h
@@ -20,14 +20,42 @@
  *             extension libraries.  They could be written in C++98.
  * @brief      Public APIs related to ::rb_mComparable.
  */
+#include "ruby/internal/attr/cold.h"
+#include "ruby/internal/attr/noreturn.h"
 #include "ruby/internal/dllexport.h"
 #include "ruby/internal/value.h"
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
+/* bignum.c */
+
+/**
+ * Canonicalises the passed `val`, which is the return value of `a <=> b`, into
+ * C's `{-1, 0, 1}`.  This can be  handy when you implement a callback function
+ * to pass to `qsort(3)` etc.
+ *
+ * @param[in]  val           Return value of a space ship operator.
+ * @param[in]  a             Comparison LHS.
+ * @param[in]  b             Comparison RHS.
+ * @exception  rb_eArgError  `a` and `b` are not comparable each other.
+ * @retval     -1            `val` is less than zero.
+ * @retval     0             `val` is equal to zero.
+ * @retval     1             `val` is greater than zero.
+ */
+int rb_cmpint(VALUE val, VALUE a, VALUE b);
+
 /* compar.c */
-int rb_cmpint(VALUE, VALUE, VALUE);
-NORETURN(void rb_cmperr(VALUE, VALUE));
+
+RBIMPL_ATTR_COLD()
+RBIMPL_ATTR_NORETURN()
+/**
+ * Raises "comparison failed" error.
+ *
+ * @param[in]  a             Comparison LHS.
+ * @param[in]  b             Comparison RHS.
+ * @exception  rb_eArgError  `a` and `b` are not comparable each other.
+ */
+void rb_cmperr(VALUE a, VALUE b);
 
 RBIMPL_SYMBOL_EXPORT_END()