From a3e72804cdeb1618b1c375e23d9ace20245a5e1c Mon Sep 17 00:00:00 2001
From: "Yukihiro \"Matz\" Matsumoto" <matz@ruby.or.jp>
Date: Tue, 3 Jun 2025 08:56:41 +0900
Subject: [PATCH] range.c: add descriptive comments to MRB_API functions in
 src/range.c

This commit adds descriptive comments to the following functions:

- mrb_range_ptr
- mrb_range_new
- mrb_range_beg_len

The comments were written by Google Jules.
---
 src/range.c | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/src/range.c b/src/range.c
index 4d8356be3..b068d80c1 100644
--- a/src/range.c
+++ b/src/range.c
@@ -472,6 +472,17 @@ mrb_gc_mark_range(mrb_state *mrb, struct RRange *r)
   return 2;
 }
 
+/**
+ * Retrieves a pointer to the internal RRange structure from a Range object.
+ *
+ * This function ensures that the given Range object is properly initialized
+ * before returning a pointer to its data. If the Range is not initialized,
+ * it raises an E_ARGUMENT_ERROR.
+ *
+ * @param mrb The mruby state.
+ * @param range The Range object (mrb_value) from which to get the pointer.
+ * @return A pointer to the struct RRange.
+ */
 MRB_API struct RRange*
 mrb_range_ptr(mrb_state *mrb, mrb_value range)
 {
@@ -484,6 +495,18 @@ mrb_range_ptr(mrb_state *mrb, mrb_value range)
   return r;
 }
 
+/**
+ * Creates a new Range object.
+ *
+ * This function allocates and initializes a new Range object with the given
+ * beginning and end values, and an exclude_end flag.
+ *
+ * @param mrb The mruby state.
+ * @param beg The beginning value of the range.
+ * @param end The end value of the range.
+ * @param excl A boolean flag indicating whether the end value is excluded (true) or included (false).
+ * @return The new Range object (mrb_value).
+ */
 MRB_API mrb_value
 mrb_range_new(mrb_state *mrb, mrb_value beg, mrb_value end, mrb_bool excl)
 {
@@ -491,6 +514,26 @@ mrb_range_new(mrb_state *mrb, mrb_value beg, mrb_value end, mrb_bool excl)
   return mrb_range_value(r);
 }
 
+/**
+ * Calculates the beginning position and length of a range.
+ *
+ * This function is typically used to get array offsets.
+ * It interprets the range as a sequence of integers.
+ * - If the beginning of the range is nil, it's treated as 0.
+ * - If the end of the range is nil, it's treated as -1 (or the last element).
+ *
+ * The function handles negative indices, out-of-bounds conditions,
+ * and truncation based on the provided length and trunc flag.
+ *
+ * @param mrb The mruby state.
+ * @param range The Range object (mrb_value).
+ * @param[out] begp Pointer to store the calculated beginning position.
+ * @param[out] lenp Pointer to store the calculated length.
+ * @param len The length of the sequence the range is being applied to.
+ * @param trunc If true, truncate the range to fit within the given length.
+ * @return An enum mrb_range_beg_len indicating success (MRB_RANGE_OK),
+ *         type mismatch (MRB_RANGE_TYPE_MISMATCH), or out of bounds (MRB_RANGE_OUT).
+ */
 MRB_API enum mrb_range_beg_len
 mrb_range_beg_len(mrb_state *mrb, mrb_value range, mrb_int *begp, mrb_int *lenp, mrb_int len, mrb_bool trunc)
 {