https://git.ruby-lang.org/ruby.git/commit/?id=9eab1e9107

From 9eab1e910768c51fd78288263a1432723d4e0b6c 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: Tue, 26 Jan 2021 11:07:18 +0900
Subject: include/ruby/internal/arithmetic/char.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/arithmetic/char.h | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/include/ruby/internal/arithmetic/char.h b/include/ruby/internal/arithmetic/char.h
index 91f06bb..920fdc0 100644
--- a/include/ruby/internal/arithmetic/char.h
+++ b/include/ruby/internal/arithmetic/char.h
@@ -29,9 +29,9 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/char.h#L29
 #include "ruby/internal/core/rstring.h"
 #include "ruby/internal/value_type.h"
 
-#define RB_NUM2CHR rb_num2char_inline
-#define NUM2CHR    RB_NUM2CHR
-#define CHR2FIX    RB_CHR2FIX
+#define RB_NUM2CHR rb_num2char_inline /**< @alias{rb_num2char_inline} */
+#define NUM2CHR    RB_NUM2CHR         /**< @old{RB_NUM2CHR} */
+#define CHR2FIX    RB_CHR2FIX         /**< @old{RB_CHR2FIX} */
 
 /** @cond INTERNAL_MACRO */
 #define RB_CHR2FIX RB_CHR2FIX
@@ -40,12 +40,35 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/char.h#L40
 RBIMPL_ATTR_CONST_UNLESS_DEBUG()
 RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14)
 RBIMPL_ATTR_ARTIFICIAL()
+/**
+ * Converts a C's `unsigned char` into an instance of ::rb_cInteger.
+ *
+ * @param[in]  c  Arbitrary `unsigned char` value.
+ * @return     An instance of ::rb_cInteger.
+ *
+ * @internal
+ *
+ * Nobody explicitly states this but in  Ruby, a char means an unsigned integer
+ * value of  range 0..255.   This is  a general principle.   AFAIK there  is no
+ * single line of code where char is signed.
+ */
 static inline VALUE
 RB_CHR2FIX(unsigned char c)
 {
     return RB_INT2FIX(c);
 }
 
+/**
+ * Converts an instance of ::rb_cNumeric into  C's `char`.  At the same time it
+ * accepts a String of more than one character, and returns its first byte.  In
+ * the  early days  there  was a  Ruby level  "character"  literal `?c`,  which
+ * roughly worked this way.
+ *
+ * @param[in]  x               Either a string or a numeric.
+ * @exception  rb_eTypeError   `x` is not a numeric.
+ * @exception  rb_eRangeError  `x` is out of range of `unsigned int`.
+ * @return     The passed value converted into C's `char`.
+ */
 static inline char
 rb_num2char_inline(VALUE x)
 {
-- 
cgit v1.1


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