https://git.ruby-lang.org/ruby.git/commit/?id=949220d9db

From 949220d9dba4a86697798302ec7bf5b4ebe3230a 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 14:39:57 +0900
Subject: include/ruby/internal/intern/range.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/intern/range.h | 58 ++++++++++++++++++++++++++++++++++--
 1 file changed, 56 insertions(+), 2 deletions(-)

diff --git a/include/ruby/internal/intern/range.h b/include/ruby/internal/intern/range.h
index 30abf02..1f7d7c3 100644
--- a/include/ruby/internal/intern/range.h
+++ b/include/ruby/internal/intern/range.h
@@ -20,14 +20,68 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/range.h#L20
  *             extension libraries.  They could be written in C++98.
  * @brief      Public APIs related to ::rb_cRange.
  */
+#include "ruby/internal/attr/nonnull.h"
 #include "ruby/internal/dllexport.h"
 #include "ruby/internal/value.h"
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
 /* range.c */
-VALUE rb_range_new(VALUE, VALUE, int);
-VALUE rb_range_beg_len(VALUE, long*, long*, long, int);
+
+/**
+ * Creates a new Range.
+ *
+ * @param[in]  beg           "Left" or "lowest" endpoint of the range.
+ * @param[in]  end           "Right" or "highest" endpoint of the range.
+ * @param[in]  excl          Whether the range is open-ended.
+ * @exception  rb_eArgError  `beg` and `end` are not comparable.
+ * @note       These days both  endpoints can be ::RUBY_Qnil,  which means that
+ *             endpoint is unbound.
+ */
+VALUE rb_range_new(VALUE beg, VALUE end, int excl);
+
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Deconstructs  a numerical  range.  As  the  arguments are  `long` based,  it
+ * expects everything are in the `long` domain.
+ *
+ * @param[in]   range           A range of numerical endpoints.
+ * @param[out]  begp            Return value buffer.
+ * @param[out]  lenp            Return value buffer.
+ * @param[in]   len             Updated length.
+ * @param[in]   err             In case `len` is out of range...
+ *                                - `0`: returns ::RUBY_Qnil.
+ *                                - `1`: raises  ::rb_eRangeError.
+ *                                - `2`: `beg` and `len` expanded accordingly.
+ * @exception   rb_eTypeError   `range` is not a numerical range.
+ * @exception   rb_eRangeError  `range` cannot fit into `long`.
+ * @retval      RUBY_Qfalse     `range` is not an ::rb_cRange.
+ * @retval      RUBY_Qnil       `len` is out of `range` but `err` is zero.
+ * @retval      RUBY_Qtrue      Otherwise.
+ * @post        `beg` is the (possibly updated) left endpoint.
+ * @post        `len` is the (possibly updated) length of the range.
+ *
+ * @internal
+ *
+ * The complex  error handling  switch reflects the  fact that  `Array#[]=` and
+ * `String#[]=` behave differently when they take ranges.
+ */
+VALUE rb_range_beg_len(VALUE range, long *begp, long *lenp, long len, int err);
+
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Deconstructs a range into its components.
+ *
+ * @param[in]   range        Range or range-ish object.
+ * @param[out]  begp         Return value buffer.
+ * @param[out]  endp         Return value buffer.
+ * @param[out]  exclp        Return value buffer.
+ * @retval      RUBY_Qfalse  `range` is not an instance of ::rb_cRange.
+ * @retval      RUBY_Qtrue   Argument pointers are updated.
+ * @post        `*begp` is the left endpoint of the range.
+ * @post        `*endp` is the right endpoint of the range.
+ * @post        `*exclp` is whether the range is open-ended or not.
+ */
 int rb_range_values(VALUE range, VALUE *begp, VALUE *endp, int *exclp);
 
 RBIMPL_SYMBOL_EXPORT_END()
-- 
cgit v1.1


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