From 540bbc71e6989b29081b6a4aea0733034b879f89 Mon Sep 17 00:00:00 2001
From: "Yukihiro \"Matz\" Matsumoto" <matz@ruby.or.jp>
Date: Fri, 11 Jul 2025 09:16:21 +0900
Subject: [PATCH] mruby-numeric-ext: add documentation for public methods

This commit adds `call-seq` documentation to the following methods
in `mruby-numeric-ext` to improve code clarity and maintainability:

- `Integer#even?`
- `Integer#odd?`
- `Integer.sqrt`
- `Float#remainder`

Additionally, it adds a comment to the internal `isqrt` function
to explain its implementation.

Co-authored-by: Gemini <gemini@google.com>
---
 mrbgems/mruby-numeric-ext/src/numeric_ext.c | 38 +++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/mrbgems/mruby-numeric-ext/src/numeric_ext.c b/mrbgems/mruby-numeric-ext/src/numeric_ext.c
index b8a8bb3d7..445464438 100644
--- a/mrbgems/mruby-numeric-ext/src/numeric_ext.c
+++ b/mrbgems/mruby-numeric-ext/src/numeric_ext.c
@@ -227,6 +227,12 @@ int_size(mrb_state *mrb, mrb_value self)
   return mrb_fixnum_value((mrb_int)size);
 }
 
+/*
+ *  call-seq:
+ *    int.even? -> true or false
+ *
+ *  Returns +true+ if +int+ is an even number.
+ */
 static mrb_value
 int_even(mrb_state *mrb, mrb_value self)
 {
@@ -240,6 +246,12 @@ int_even(mrb_state *mrb, mrb_value self)
   return mrb_bool_value(mrb_integer(self) % 2 == 0);
 }
 
+/*
+ *  call-seq:
+ *    int.odd? -> true or false
+ *
+ *  Returns +true+ if +int+ is an odd number.
+ */
 static mrb_value
 int_odd(mrb_state *mrb, mrb_value self)
 {
@@ -249,6 +261,14 @@ int_odd(mrb_state *mrb, mrb_value self)
 }
 
 #ifndef MRB_NO_FLOAT
+/*
+ *  call-seq:
+ *     num.remainder(numeric)  ->  real
+ *
+ *  <code>x.remainder(y)</code> means <code>x-y*(x/y).truncate</code>.
+ *
+ *  See Numeric#divmod.
+ */
 static mrb_value
 flo_remainder(mrb_state *mrb, mrb_value self)
 {
@@ -262,6 +282,11 @@ flo_remainder(mrb_state *mrb, mrb_value self)
 }
 #endif
 
+/*
+ * Integer square root implementation using the Babylonian method.
+ * This is an efficient integer-only algorithm to find the largest
+ * integer `x` such that `x*x <= n`.
+ */
 static mrb_int
 isqrt(mrb_int n)
 {
@@ -280,6 +305,19 @@ isqrt(mrb_int n)
   return x;
 }
 
+/*
+ *  call-seq:
+ *    Integer.sqrt(n) -> integer
+ *
+ *  Returns the integer square root of the non-negative integer +n+,
+ *  which is the largest integer `i` such that `i*i <= n`.
+ *
+ *    Integer.sqrt(0)    # => 0
+ *    Integer.sqrt(1)    # => 1
+ *    Integer.sqrt(24)   # => 4
+ *    Integer.sqrt(25)   # => 5
+ *    Integer.sqrt(10**40) # => 10**20
+ */
 static mrb_value
 int_sqrt(mrb_state *mrb, mrb_value self)
 {