summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
author卜部昌平 <shyouhei@ruby-lang.org>2021-01-11 18:39:29 +0900
committer卜部昌平 <shyouhei@ruby-lang.org>2021-09-10 20:00:06 +0900
commit178ce745975134b87aacb3d42e383011e4350ed4 (patch)
treed28e0202b863519bf9d926997a454d38d42cf38d
parente2a441bdd4584292deaf85906d747521ad2e9f2a (diff)
include/ruby/internal/value.h: add doxygen
Must not be a bad idea to improve documents. [ci skip]
Notes
Notes: Merged: https://github.com/ruby/ruby/pull/4815
-rw-r--r--include/ruby/internal/value.h69
1 files changed, 68 insertions, 1 deletions
diff --git a/include/ruby/internal/value.h b/include/ruby/internal/value.h
index 709cd40407..805cd83513 100644
--- a/include/ruby/internal/value.h
+++ b/include/ruby/internal/value.h
@@ -24,7 +24,72 @@
#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;
# 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 */