Documentation

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 162 insertions, 3 deletions

diff --git a/libsimple/vallocz.h b/libsimple/vallocz.h
index 2831cf8..a4765c5 100644
--- a/libsimple/vallocz.h
+++ b/libsimple/vallocz.h
@@ -1,9 +1,23 @@
 /* See LICENSE file for copyright and license details. */
 
-/*
- * The alignment will be the page size.
- */
 
+/**
+ * Dynamically allocates heap allocated, optionally
+ * initialised, memory with page size alignment
+ * 
+ * The product of all arguments except `clear`, up to the
+ * first 0, will be used as the number of bytes to allocated
+ * 
+ * @param   clear   Non-zero if the memory should be initialised
+ * @param   n       First factor for the allocation size, must not be 0
+ * @param   ap      The rest of the factors for the allocation size,
+ *                  all arguments should have the type `size_t`, and
+ *                  list must end with 0 (which is not factor)
+ * @return          A unique pointer with at least the specified size
+ *                  and with page size alignment; `NULL` on failure
+ * @throws  EINVAL  `n` is 0
+ * @throws  ENOMEM  Could not allocated enough memory
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__)))
 static inline void *
 libsimple_vvalloczn(int __clear, size_t __n, va_list __ap) /* TODO test ([v]valloc[z]n) */
@@ -17,6 +31,18 @@ libsimple_vvalloczn(int __clear, size_t __n, va_list __ap) /* TODO test ([v]vall
 # define vvalloczn libsimple_vvalloczn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optionally
+ * initialised, memory with page size alignment
+ * 
+ * @param   clear   Non-zero if the memory should be initialised
+ * @param   n       The number of bytes to allocate
+ * @return          A unique pointer with at least the specified size
+ *                  and with page size alignment; `NULL` on failure
+ * @throws  EINVAL  `n` is 0
+ * @throws  ENOMEM  Could not allocated enough memory
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2), __warn_unused_result__)))
 static inline void *
 libsimple_vallocz(int __clear, size_t __n) /* TODO test (valloc[z]) */
@@ -30,6 +56,24 @@ libsimple_vallocz(int __clear, size_t __n) /* TODO test (valloc[z]) */
 # define vallocz libsimple_vallocz
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optionally
+ * initialised, memory with page size alignment
+ * 
+ * The product of all arguments except `clear`, up to the
+ * first 0, will be used as the number of bytes to allocated
+ * 
+ * @param   clear   Non-zero if the memory should be initialised
+ * @param   n       First factor for the allocation size, must not be 0
+ * @param   ...     The rest of the factors for the allocation size,
+ *                  all arguments should have the type `size_t`, and
+ *                  list must end with 0 (which is not factor)
+ * @return          A unique pointer with at least the specified size
+ *                  and with page size alignment; `NULL` on failure
+ * @throws  EINVAL  `n` is 0
+ * @throws  ENOMEM  Could not allocated enough memory
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__)))
 static inline void *
 libsimple_valloczn(int __clear, size_t __n, ... /*, (size_t)0 */)
@@ -43,6 +87,22 @@ libsimple_valloczn(int __clear, size_t __n, ... /*, (size_t)0 */)
 # define valloczn libsimple_valloczn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optionally
+ * initialised, memory with page size alignment
+ * 
+ * On failure, the `libsimple_enprintf` function is called,
+ * cause the program to print an error message and exit,
+ * see `libsimple_enprintf` for more information
+ * 
+ * @param   status  The exit value for the process in case of failure
+ * @param   clear   Non-zero if the memory should be initialised
+ * @param   n       The number of bytes to allocate, the behaviour of
+ *                  this function is unspecified for the value 0
+ * @return          A unique pointer with at least the specified size
+ *                  and with page size alignment
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(3), __warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_envallocz(int __status, int __clear, size_t __n) /* TODO test (e[n]valloc[z]) */
@@ -56,6 +116,28 @@ libsimple_envallocz(int __status, int __clear, size_t __n) /* TODO test (e[n]val
 # define envallocz libsimple_envallocz
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optionally
+ * initialised, memory with page size alignment
+ * 
+ * The product of all arguments except `status` and
+ * `clear`, up to the first 0, will be used as the number
+ * of bytes to allocated
+ * 
+ * On failure, the `libsimple_enprintf` function is called,
+ * cause the program to print an error message and exit,
+ * see `libsimple_enprintf` for more information
+ * 
+ * @param   status  The exit value for the process in case of failure
+ * @param   clear   Non-zero if the memory should be initialised
+ * @param   n       First factor for the allocation size, must not be 0
+ * @param   ap      The rest of the factors for the allocation size,
+ *                  all arguments should have the type `size_t`, and
+ *                  list must end with 0 (which is not factor)
+ * @return          A unique pointer with at least the specified size
+ *                  and with page size alignment
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_envvalloczn(int __status, int __clear, size_t __n, va_list __ap) /* TODO test (e[n][v]valloc[z]n, e[n]vallocn) */
@@ -70,6 +152,28 @@ libsimple_envvalloczn(int __status, int __clear, size_t __n, va_list __ap) /* TO
 # define envvalloczn libsimple_envvalloczn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optionally
+ * initialised, memory with page size alignment
+ * 
+ * The product of all arguments except `status` and
+ * `clear`, up to the first 0, will be used as the number
+ * of bytes to allocated
+ * 
+ * On failure, the `libsimple_enprintf` function is called,
+ * cause the program to print an error message and exit,
+ * see `libsimple_enprintf` for more information
+ * 
+ * @param   status  The exit value for the process in case of failure
+ * @param   clear   Non-zero if the memory should be initialised
+ * @param   n       First factor for the allocation size, must not be 0
+ * @param   ...     The rest of the factors for the allocation size,
+ *                  all arguments should have the type `size_t`, and
+ *                  list must end with 0 (which is not factor)
+ * @return          A unique pointer with at least the specified size
+ *                  and with page size alignment
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_envalloczn(int __status, int __clear, size_t __n, ... /*, (size_t)0 */)
@@ -83,6 +187,21 @@ libsimple_envalloczn(int __status, int __clear, size_t __n, ... /*, (size_t)0 */
 # define envalloczn libsimple_envalloczn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optionally
+ * initialised, memory with page size alignment
+ * 
+ * On failure, the `libsimple_eprintf` function is called,
+ * cause the program to print an error message and exit,
+ * see `libsimple_eprintf` for more information
+ * 
+ * @param   clear  Non-zero if the memory should be initialised
+ * @param   n      The number of bytes to allocate, the behaviour of
+ *                 this function is unspecified for the value 0
+ * @return         A unique pointer with at least the specified size
+ *                 and with page size alignment
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2), __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_evallocz(int __clear, size_t __n)
 { return libsimple_envallocz(libsimple_default_failure_exit, __clear, __n); }
@@ -90,6 +209,26 @@ static inline void *libsimple_evallocz(int __clear, size_t __n)
 # define evallocz libsimple_evallocz
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optionally
+ * initialised, memory with page size alignment
+ * 
+ * The product of all arguments except `clear`, up to the
+ * first 0, will be used as the number of bytes to allocated
+ * 
+ * On failure, the `libsimple_eprintf` function is called,
+ * cause the program to print an error message and exit,
+ * see `libsimple_eprintf` for more information
+ * 
+ * @param   clear  Non-zero if the memory should be initialised
+ * @param   n      First factor for the allocation size, must not be 0
+ * @param   ap     The rest of the factors for the allocation size,
+ *                 all arguments should have the type `size_t`, and
+ *                 list must end with 0 (which is not factor)
+ * @return         A unique pointer with at least the specified size
+ *                 and with page size alignment
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_evvalloczn(int __clear, size_t __n, va_list __ap)
 { return libsimple_envvalloczn(libsimple_default_failure_exit, __clear, __n, __ap); }
@@ -97,6 +236,26 @@ static inline void *libsimple_evvalloczn(int __clear, size_t __n, va_list __ap)
 # define evvalloczn libsimple_evvalloczn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optionally
+ * initialised, memory with page size alignment
+ * 
+ * The product of all arguments except `clear`, up to the
+ * first 0, will be used as the number of bytes to allocated
+ * 
+ * On failure, the `libsimple_eprintf` function is called,
+ * cause the program to print an error message and exit,
+ * see `libsimple_eprintf` for more information
+ * 
+ * @param   clear  Non-zero if the memory should be initialised
+ * @param   n      First factor for the allocation size, must not be 0
+ * @param   ...    The rest of the factors for the allocation size,
+ *                 all arguments should have the type `size_t`, and
+ *                 list must end with 0 (which is not factor)
+ * @return         A unique pointer with at least the specified size
+ *                 and with page size alignment
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_evalloczn(int __clear, size_t __n, ... /*, (size_t)0 */)