Mercurial > hg > ucx / changeset

--- a/src/cx/common.h	Sat Jan 04 16:10:53 2025 +0100
+++ b/src/cx/common.h	Sat Jan 04 17:37:47 2025 +0100
@@ -27,15 +27,15 @@
  */
 
 /**
- * \file common.h
+ * @file common.h
  *
- * \brief Common definitions and feature checks.
+ * @brief Common definitions and feature checks.
  *
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
  *
- * \mainpage UAP Common Extensions
+ * @mainpage UAP Common Extensions
  * Library with common and useful functions, macros and data structures.
  * <p>
  * Latest available source:<br>
@@ -102,6 +102,9 @@
 //       Architecture Detection
 // ---------------------------------------------------------------------------
 
+#ifndef INTPTR_MAX
+#error Missing INTPTR_MAX definition
+#endif
 #if INTPTR_MAX == INT64_MAX
 /**
  * The address width in bits on this platform.
@@ -122,6 +125,9 @@
 
 #ifndef SSIZE_MAX // not defined in glibc since C23 and MSVC
 #if CX_WORDSIZE == 64
+/**
+ * The maximum representable value in ssize_t.
+ */
 #define SSIZE_MAX 0x7fffffffffffffffll
 #else
 #define SSIZE_MAX 0x7fffffffl
@@ -163,10 +169,10 @@
 #ifndef __clang__
 /**
  * The pointer returned by the attributed function is supposed to be freed
- * by \p freefunc.
+ * by @p freefunc.
  *
  * @param freefunc the function that shall be used to free the memory
- * @param freefunc_arg the index of the pointer argument in \p freefunc
+ * @param freefunc_arg the index of the pointer argument in @p freefunc
  */
 #define cx_attr_dealloc(freefunc, freefunc_arg) \
     __attribute__((__malloc__(freefunc, freefunc_arg)))
@@ -190,7 +196,7 @@
 
 #ifdef __clang__
 /**
- * No support for \c null_terminated_string_arg in clang or GCC below 14.
+ * No support for @c null_terminated_string_arg in clang or GCC below 14.
  */
 #define cx_attr_cstr_arg(idx)
 /**
@@ -211,7 +217,7 @@
 #endif // __GNUC__ < 10
 #if __GNUC__ < 14
 /**
- * No support for \c null_terminated_string_arg in clang or GCC below 14.
+ * No support for @c null_terminated_string_arg in clang or GCC below 14.
  */
 #define cx_attr_cstr_arg(idx)
 #else
@@ -288,7 +294,7 @@
         size_t,
         size_t,
         void *
-) cx_attr_nonnull;
+);
 
 /**
  * Function pointer compatible with fread-like functions.
@@ -298,7 +304,7 @@
         size_t,
         size_t,
         void *
-) cx_attr_nonnull;
+);
 
 // ---------------------------------------------------------------------------
 //       Utility macros
@@ -321,52 +327,36 @@
 
 #if (__GNUC__ >= 5 || defined(__clang__)) && !defined(CX_NO_SZMUL_BUILTIN)
 #define CX_SZMUL_BUILTIN
-
-/**
- * Alias for \c __builtin_mul_overflow.
- *
- * Performs a multiplication of size_t values and checks for overflow.
- *
- * @param a first operand
- * @param b second operand
- * @param result a pointer to a size_t, where the result should
- * be stored
- * @return zero, if no overflow occurred and the result is correct, non-zero
- * otherwise
- */
 #define cx_szmul(a, b, result) __builtin_mul_overflow(a, b, result)
-
 #else // no GNUC or clang bultin
-
 /**
  * Performs a multiplication of size_t values and checks for overflow.
   *
- * @param a first operand
- * @param b second operand
- * @param result a pointer to a size_t, where the result should
+ * @param a (@c size_t) first operand
+ * @param b (@c size_t) second operand
+ * @param result (@c size_t*) a pointer to a variable, where the result should
  * be stored
- * @return zero, if no overflow occurred and the result is correct, non-zero
- * otherwise
+ * @retval zero success
+ * @retval non-zero the multiplication would overflow
  */
 #define cx_szmul(a, b, result) cx_szmul_impl(a, b, result)
 
 /**
- * Performs a multiplication of size_t values and checks for overflow.
+ * Implementation of cx_szmul() when no compiler builtin is available.
  *
- * This is a custom implementation in case there is no compiler builtin
- * available.
+ * Do not use in application code.
  *
  * @param a first operand
  * @param b second operand
- * @param result a pointer to a size_t where the result should be stored
- * @return zero, if no overflow occurred and the result is correct, non-zero
- * otherwise
+ * @param result a pointer to a variable, where the result should
+ * be stored
+ * @retval zero success
+ * @retval non-zero the multiplication would overflow
  */
 #if __cplusplus
 extern "C"
 #endif
 int cx_szmul_impl(size_t a, size_t b, size_t *result);
-
 #endif // cx_szmul