https://git.ruby-lang.org/ruby.git/commit/?id=178ce74597

From 178ce745975134b87aacb3d42e383011e4350ed4 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: Mon, 11 Jan 2021 18:39:29 +0900
Subject: include/ruby/internal/value.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/value.h | 69 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 1 deletion(-)

diff --git a/include/ruby/internal/value.h b/include/ruby/internal/value.h
index 709cd40..805cd83 100644
--- a/include/ruby/internal/value.h
+++ b/include/ruby/internal/value.h
@@ -24,7 +24,72 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/value.h#L24
 #include "ruby/backward/2/long_long.h"
 #include "ruby/backward/2/limits.h"
 
-#if defined HAVE_UINTPTR_T && 0
+#if defined(__DOXYGEN__)
+
+/**
+ * Type that represents a Ruby object.  It is an unsigned integer of some kind,
+ * depending on platforms.
+ *
+ * ```CXX
+ * VALUE value = rb_eval_string("ARGF.readlines.map.with_index");
+ * ```
+ *
+ * @warning  ::VALUE is not a pointer.
+ * @warning  ::VALUE can be wider than `long`.
+ */
+typedef uintptr_t VALUE;
+
+/**
+ * Type that represents a Ruby identifier such as a variable name.
+ *
+ * ```CXX
+ * ID method = rb_intern("method");
+ * VALUE result = rb_funcall(obj, method, 0);
+ * ```
+ *
+ * @note  ::rb_cSymbol is a Ruby-level data type for the same thing.
+ */
+typedef uintptr_t ID;
+
+/**
+ * A signed integer type that has the same width with ::VALUE.
+ *
+ * @internal
+ *
+ * @shyouhei wonders: is it guaranteed  that `uintptr_t` and `intptr_t` are the
+ * same width?  As far as I read ISO/IEC 9899:2018 section 7.20.1.4 paragraph 1
+ * no such description is given... or defined elsewhere?
+ */
+typedef intptr_t SIGNED_VALUE;
+
+/**
+ * Identical to  `sizeof(VALUE)`, except it  is a macro  that can also  be used
+ * inside of preprocessor directives such as `#if`.  Handy on occasions.
+ */
+#define SIZEOF_VALUE SIZEOF_UINTPTR_T
+
+/**
+ * @private
+ *
+ * A compile-time constant of type ::VALUE whose value is 0.
+ */
+#define RBIMPL_VALUE_NULL UINTPTR_C(0)
+
+/**
+ * @private
+ *
+ * A compile-time constant of type ::VALUE whose value is 1.
+ */
+#define RBIMPL_VALUE_ONE  UINTPTR_C(1)
+
+/**
+ * @private
+ *
+ * Maximum possible value that a ::VALUE can take.
+ */
+#define RBIMPL_VALUE_FULL UINTPTR_MAX
+
+#elif defined HAVE_UINTPTR_T && 0
 typedef uintptr_t VALUE;
 typedef uintptr_t ID;
 # define SIGNED_VALUE intptr_t
@@ -59,8 +124,10 @@ typedef unsigned LONG_LONG ID; https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/value.h#L124
 # error ---->> ruby requires sizeof(void*) == sizeof(long) or sizeof(LONG_LONG) to be compiled. <<----
 #endif
 
+/** @cond INTERNAL_MACRO */
 RBIMPL_STATIC_ASSERT(sizeof_int, SIZEOF_INT == sizeof(int));
 RBIMPL_STATIC_ASSERT(sizeof_long, SIZEOF_LONG == sizeof(long));
 RBIMPL_STATIC_ASSERT(sizeof_long_long, SIZEOF_LONG_LONG == sizeof(LONG_LONG));
 RBIMPL_STATIC_ASSERT(sizeof_voidp, SIZEOF_VOIDP == sizeof(void *));
+/** @endcond */
 #endif /* RBIMPL_VALUE_H */
-- 
cgit v1.1


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