https://git.ruby-lang.org/ruby.git/commit/?id=7c8ad0a37d

From 7c8ad0a37d983f44f2ecb8a304fb926e31cac08b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?=
 <shyouhei@r...>
Date: Thu, 25 Feb 2021 11:44:19 +0900
Subject: include/ruby/internal/intern/rational.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/intern/rational.h | 136 ++++++++++++++++++++++++++++++--
 1 file changed, 131 insertions(+), 5 deletions(-)

diff --git a/include/ruby/internal/intern/rational.h b/include/ruby/internal/intern/rational.h
index a3d3701..ff4beca 100644
--- a/include/ruby/internal/intern/rational.h
+++ b/include/ruby/internal/intern/rational.h
@@ -20,6 +20,7 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/rational.h#L20
  *             extension libraries.  They could be written in C++98.
  * @brief      Public APIs related to ::rb_cRational.
  */
+#include "ruby/internal/attr/pure.h"
 #include "ruby/internal/dllexport.h"
 #include "ruby/internal/value.h"
 #include "ruby/internal/arithmetic/long.h" /* INT2FIX is here. */
@@ -27,19 +28,144 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/rational.h#L28
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
 /* rational.c */
-VALUE rb_rational_raw(VALUE, VALUE);
+
+/**
+ * Identical to rb_rational_new(), except it skips argument validations.  It is
+ * thus  dangerous  for extension  libraries.   For  instance `1/0r`  could  be
+ * constructed using this.
+ *
+ * @param[in]  num            Numerator, an instance of ::rb_cInteger.
+ * @param[in]  den            Denominator, an instance of ::rb_cInteger.
+ * @exception  rb_eTypeError  Either argument is not an Integer.
+ * @return     An instance of ::rb_cRational whose value is `(num/den)r`.
+ */
+VALUE rb_rational_raw(VALUE num, VALUE den);
+
+/**
+ * Shorthand  of  `(x/1)r`.  As  `x`  is  already  an Integer,  it  practically
+ * converts it into a Rational of the identical value.
+ *
+ * @param[in]  x  An instance of ::rb_cInteger.
+ * @return     An instance of ::rb_cRational, whose value is `(x/1)r`.
+ */
 #define rb_rational_raw1(x) rb_rational_raw((x), INT2FIX(1))
+
+/** @alias{rb_rational_raw} */
 #define rb_rational_raw2(x,y) rb_rational_raw((x), (y))
-VALUE rb_rational_new(VALUE, VALUE);
+
+/**
+ * Constructs a Rational,  with reduction.  This returns  for instance `(2/3)r`
+ * for `rb_rational_new(INT2NUM(-384), INT2NUM(-576))`.
+ *
+ * @param[in]  num               Numerator, an instance of ::rb_cInteger.
+ * @param[in]  den               Denominator, an instance of ::rb_cInteger.
+ * @exception  rb_eZeroDivError  `den` is zero.
+ * @return     An instance of ::rb_cRational whose value is `(num/den)r`.
+ */
+VALUE rb_rational_new(VALUE num, VALUE den);
+
+/**
+ * Shorthand  of  `(x/1)r`.  As  `x`  is  already  an Integer,  it  practically
+ * converts it into a Rational of the identical value.
+ *
+ * @param[in]  x  An instance of ::rb_cInteger.
+ * @return     An instance of ::rb_cRational, whose value is `(x/1)r`.
+ */
 #define rb_rational_new1(x) rb_rational_new((x), INT2FIX(1))
+
+/** @alias{rb_rational_new} */
 #define rb_rational_new2(x,y) rb_rational_new((x), (y))
-VALUE rb_Rational(VALUE, VALUE);
+
+/**
+ * Converts various values into a Rational.  This function accepts:
+ *
+ * - Instances of ::rb_cInteger (taken as-is),
+ * - Instances of ::rb_cRational (taken as-is),
+ * - Instances of ::rb_cFloat (applies `#to_r`),
+ * - Instances of ::rb_cComplex (applies `#to_r`),
+ * - Instances of ::rb_cString (applies `#to_r`),
+ * - Other objects that respond to `#to_r`.
+ *
+ * It (possibly  recursively) applies  `#to_r` until  both sides  become either
+ * Integer or Rational, then divides them.
+ *
+ * As a  special case, passing  ::RUBY_Qundef to `den`  is the same  as passing
+ * `RB_INT2NUM(1)`.
+ *
+ * @param[in]  num                   Numerator (see above).
+ * @param[in]  den                   Denominator (see above).
+ * @exception  rb_eTypeError         Passed something not described above.
+ * @exception  rb_eFloatDomainError  `#to_r` produced Nan/Inf.
+ * @exception  rb_eZeroDivError      `#to_r` produced zero for `den`.
+ * @return     An instance of ::rb_cRational whose value is `(num/den)r`.
+ *
+ * @internal
+ *
+ * This was the implementation of `Kernel#Rational` before, but they diverged.
+ */
+VALUE rb_Rational(VALUE num, VALUE den);
+
+/**
+ * Shorthand of  `(x/1)r`.  It practically converts  it into a Rational  of the
+ * identical value.
+ *
+ * @param[in]  x  ::rb_cInteger, ::rb_cRational, or  something that responds to
+ *                `#to_r`.
+ * @return     An instance of ::rb_cRational, whose value is `(x/1)r`.
+ */
 #define rb_Rational1(x) rb_Rational((x), INT2FIX(1))
+
+/** @alias{rb_Rational} */
 #define rb_Rational2(x,y) rb_Rational((x), (y))
+
+RBIMPL_ATTR_PURE()
+/**
+ * Queries the numerator of the passed Rational.
+ *
+ * @param[in]  rat  An instance of ::rb_cRational.
+ * @return     Its numerator part, which is an instance of ::rb_cInteger.
+ */
 VALUE rb_rational_num(VALUE rat);
+
+RBIMPL_ATTR_PURE()
+/**
+ * Queries the denominator of the passed Rational.
+ *
+ * @param[in]  rat  An instance of ::rb_cRational.
+ * @return     Its  denominator part,  which  is an  instance of  ::rb_cInteger
+ *             greater than or equal to one..
+ */
 VALUE rb_rational_den(VALUE rat);
-VALUE rb_flt_rationalize_with_prec(VALUE, VALUE);
-VALUE rb_flt_rationalize(VALUE);
+
+/**
+ * Simplified  approximation of  a float.   It returns  a rational  `rat` which
+ * satisfies:
+ *
+ * ```
+ * flt - |prec| <= rat <= flt + |prec|
+ * ```
+ *
+ * ```ruby
+ * 3.141592.rationalize(0.001) # => (201/64)r
+ * 3.141592.rationalize(0.01)' # => (22/7)r
+ * 3.141592.rationalize(0.1)'  # => (16/5)r
+ * 3.141592.rationalize(1)'    # => (3/1)r
+ * ```
+ *
+ * @param[in]  flt   An instance of ::rb_cFloat to rationalise.
+ * @param[in]  prec  Another ::rb_cFloat, which is the "precision".
+ * @return     Approximation of `flt`, in ::rb_cRational.
+ */
+VALUE rb_flt_rationalize_with_prec(VALUE flt, VALUE prec);
+
+/**
+ * Identical   to   rb_flt_rationalize_with_prec(),  except   it   auto-detects
+ * appropriate precision depending on the passed value.
+ *
+ * @param[in]  flt   An instance of ::rb_cFloat to rationalise.
+ * @return     Approximation of `flt`, in ::rb_cRational.
+ */
+VALUE rb_flt_rationalize(VALUE flt);
 
 RBIMPL_SYMBOL_EXPORT_END()
 
-- 
cgit v1.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/