include/ruby/util.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]

1 files changed, 183 insertions, 8 deletions

diff --git a/include/ruby/util.h b/include/ruby/util.h
index 660f91de8e..dfe215eed7 100644
--- a/include/ruby/util.h
+++ b/include/ruby/util.h
@@ -9,25 +9,119 @@
  *             Permission  is hereby  granted,  to  either redistribute  and/or
  *             modify this file, provided that  the conditions mentioned in the
  *             file COPYING are met.  Consult the file for details.
+ * @warning    DO NOT ADD RANDOM GARBAGES IN  THIS FILE!  Contents of this file
+ *             reside here for historical reasons.  Find a right place for your
+ *             API!
  */
 #include "ruby/internal/config.h"
+
+#ifdef STDC_HEADERS
+# include <stddef.h>                       /* size_t */
+#endif
+
+#if HAVE_SYS_TYPES_H
+# include <sys/types.h>                    /* ssize_t */
+#endif
+
+#include "ruby/internal/attr/nodiscard.h"
+#include "ruby/internal/attr/nonnull.h"
+#include "ruby/internal/attr/pure.h"
+#include "ruby/internal/attr/restrict.h"
+#include "ruby/internal/attr/returns_nonnull.h"
+#include "ruby/internal/config.h"
 #include "ruby/internal/dllexport.h"
 #include "ruby/defines.h"
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
+/** an approximation of ceil(n * log10(2)), up to 65536 at least */
 #define DECIMAL_SIZE_OF_BITS(n) (((n) * 3010 + 9998) / 9999)
-/* an approximation of ceil(n * log10(2)), up to 65536 at least */
 
+/**
+ * Character to  number mapping  like `'a'`  -> `10`, `'b'`  -> `11`  etc.  For
+ * punctuation etc.,  the value is  -1.  "36"  terminology comes from  the fact
+ * that this is the table behind `str.to_i(36)`.
+ */
 RUBY_EXTERN const signed char ruby_digit36_to_number_table[];
+
+/**
+ * Characters that Ruby accepts as hexadecimal digits.  This is `/\h/` expanded
+ * into an array.
+ */
 RUBY_EXTERN const char ruby_hexdigits[];
 
+/**
+ * Scans the passed string, assuming the  string is a textual representation of
+ * an  integer.  Stops  when encountering  something non-digit  for the  passed
+ * base.
+ *
+ * @note        This does not understand minus sign.
+ * @note        This does not understand e.g. `0x` prefix.
+ * @note        It is a failure to pass `0` to `base`, unlike ruby_strtoul().
+ * @param[in]   str       Target string of digits to interpret.
+ * @param[in]   len       Number of bytes of `str`, or -1 to detect `NUL`.
+ * @param[in]   base      Base, `2` to `36` inclusive.
+ * @param[out]  retlen    Return value buffer.
+ * @param[out]  overflow  Return value buffer.
+ * @return      Interpreted numeric representation of `str`.
+ * @post        `retlen` is the number of bytes scanned so far.
+ * @post       `overflow` is  set to  true if  the string  represents something
+ *              bigger than  `ULONG_MAX`.  Something meaningful  still returns;
+ *              which is the designed belabour of C's unsigned arithmetic.
+ */
 unsigned long ruby_scan_digits(const char *str, ssize_t len, int base, size_t *retlen, int *overflow);
+
+/** @old{ruby_scan_oct} */
 #define scan_oct(s,l,e) ((int)ruby_scan_oct((s),(l),(e)))
-unsigned long ruby_scan_oct(const char *, size_t, size_t *);
+
+RBIMPL_ATTR_PURE()
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Interprets  the passed  string as  an  octal unsigned  integer.  Stops  when
+ * encounters something not understood.
+ *
+ * @param[in]   str       C string to scan.
+ * @param[in]   len       Length of `str`.
+ * @param[out]  consumed  Return value buffer.
+ * @return      Parsed integer.
+ * @post        `ret` is the number of characters read.
+ *
+ * @internal
+ *
+ * No consideration  is made  for integer  overflows.  As  the return  value is
+ * unsigned this function  has fully defined behaviour, but you  cannot know if
+ * there was an integer wrap-around or not.
+ */
+unsigned long ruby_scan_oct(const char *str, size_t len, size_t *consumed);
+
+/** @old{ruby_scan_hex} */
 #define scan_hex(s,l,e) ((int)ruby_scan_hex((s),(l),(e)))
-unsigned long ruby_scan_hex(const char *, size_t, size_t *);
 
+RBIMPL_ATTR_PURE()
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Interprets the  passed string  a hexadecimal  unsigned integer.   Stops when
+ * encounters something not understood.
+ *
+ * @param[in]   str  C string to scan.
+ * @param[in]   len  Length of `str`.
+ * @param[out]  ret  Return value buffer.
+ * @return      Parsed integer.
+ * @post        `ret` is the number of characters read.
+ *
+ * @internal
+ *
+ * No consideration  is made  for integer  overflows.  As  the return  value is
+ * unsigned this function  has fully defined behaviour, but you  cannot know if
+ * there was an integer wrap-around or not.
+ */
+unsigned long ruby_scan_hex(const char *str, size_t len, size_t *ret);
+
+/**
+ * Reentrant implementation of  quick sort.  If your  system provides something
+ * (like  C11 qsort_s),  this is  a thin  wrapper of  that routine.   Otherwise
+ * resorts to our own version.
+ */
 #ifdef HAVE_GNU_QSORT_R
 # define ruby_qsort qsort_r
 #else
@@ -35,20 +129,101 @@ void ruby_qsort(void *, const size_t, const size_t,
 		int (*)(const void *, const void *, void *), void *);
 #endif
 
-void ruby_setenv(const char *, const char *);
-void ruby_unsetenv(const char *);
+RBIMPL_ATTR_NONNULL((1))
+/**
+ * Sets  an environment  variable.   In case  of  POSIX this  is  a wrapper  of
+ * `setenv(3)`.  But there are systems which lack one.  We try hard emulating.
+ *
+ * @param[in]  key                  An environment variable.
+ * @param[in]  val                  A value to be associated with `key`, or 0.
+ * @exception  rb_eSystemCallError  `setenv(3)` failed for some reason.
+ * @post       Environment variable  `key` is created if  necessary.  Its value
+ *             is updated to be `val`.
+ */
+void ruby_setenv(const char *key, const char *val);
+
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Deletes the passed environment variable, if any.
+ *
+ * @param[in]  key                  An environment variable.
+ * @exception  rb_eSystemCallError  `unsetenv(3)` failed for some reason.
+ * @post       Environment variable `key` does not exist.
+ */
+void ruby_unsetenv(const char *key);
+
+RBIMPL_ATTR_NODISCARD()
+RBIMPL_ATTR_RESTRICT()
+RBIMPL_ATTR_RETURNS_NONNULL()
+RBIMPL_ATTR_NONNULL(())
+/**
+ * This is our  own version of `strdup(3)` that uses  ruby_xmalloc() instead of
+ * system malloc (benefits our GC).
+ *
+ * @param[in]  str  Target C string to duplicate.
+ * @return     An allocated C string holding the identical contents.
+ * @note       Return value must be discarded using ruby_xfree().
+ */
+char *ruby_strdup(const char *str);
 
-char *ruby_strdup(const char *);
 #undef strdup
+/**
+ * @alias{ruby_strdup}
+ *
+ * @internal
+ *
+ * @shyouhei doesn't  think it  is a wise  idea.  ruby_strdup()'s  return value
+ * must be passed to ruby_xfree(), but this macro makes it almost impossible.
+ */
 #define strdup(s) ruby_strdup(s)
 
+RBIMPL_ATTR_NODISCARD()
+RBIMPL_ATTR_RESTRICT()
+RBIMPL_ATTR_RETURNS_NONNULL()
+/**
+ * This is our  own version of `getcwd(3)` that uses  ruby_xmalloc() instead of
+ * system malloc (benefits our GC).
+ *
+ * @return     An allocated C string holding the process working directory.
+ * @note       Return value must be discarded using ruby_xfree().
+ */
 char *ruby_getcwd(void);
 
-double ruby_strtod(const char *, char **);
+RBIMPL_ATTR_NONNULL((1))
+/**
+ * Our own locale-insensitive  version of `strtod(3)`.  The  conversion is done
+ * as if the current locale is set  to the "C" locale, no matter actual runtime
+ * locale settings.
+ *
+ * @param[in]   str     Decimal  or hexadecimal  representation  of a  floating
+ *                      point number.
+ * @param[out]  endptr  NULL, or an arbitrary pointer (overwritten on return).
+ * @return      Converted number.
+ * @post        If `endptr` is not NULL, it  is updated to point the first such
+ *              byte where conversion failed.
+ * @note        This function sets `errno` on failure.
+ *                - `ERANGE`: Converted integer is out of range of `double`.
+ * @see         William  D.   Clinger,  "How  to Read  Floating  Point  Numbers
+ *              Accurately" in Proc.  ACM SIGPLAN '90, pp.  92-101.
+ *              https://doi.org/10.1145/93542.93557
+ */
+double ruby_strtod(const char *str, char **endptr);
+
 #undef strtod
+/** @alias{ruby_strtod} */
 #define strtod(s,e) ruby_strtod((s),(e))
 
-void ruby_each_words(const char *, void (*)(const char*, int, void*), void *);
+RBIMPL_ATTR_NONNULL((2))
+/**
+ * Scans the  passed string, with calling  the callback function every  time it
+ * encounters a  "word".  A word  here is a  series of characters  separated by
+ * either a space (of IEEE 1003.1 section 7.3.1.1), or a `','`.
+ *
+ * @param[in]      str   Target string to split into each words.
+ * @param[in]      func  Callback function.
+ * @param[in,out]  argv  Passed as-is to `func`.
+ */
+void ruby_each_words(const char *str, void (*func)(const char *word, int len, void *argv), void *argv);
 
 RBIMPL_SYMBOL_EXPORT_END()