More documentation

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

3 files changed, 316 insertions, 10 deletions

diff --git a/libsimple/calloc.h b/libsimple/calloc.h
index ab73ff3..2820d02 100644
--- a/libsimple/calloc.h
+++ b/libsimple/calloc.h
@@ -1,5 +1,23 @@
 /* See LICENSE file for copyright and license details. */
 
+
+/**
+ * Dynamically allocates heap allocated, initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, up to the first 0,
+ * will be used as the number of bytes to allocated
+ * 
+ * @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 the alignment `alignof(max_align_t)`;
+ *                  `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_vcallocn(size_t __n, va_list __ap)
 { return libsimple_vmalloczn(1, __n, __ap); }
@@ -7,6 +25,24 @@ static inline void *libsimple_vcallocn(size_t __n, va_list __ap)
 # define vcallocn libsimple_vcallocn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, up to the first 0,
+ * will be used as the number of bytes to allocated
+ * 
+ * @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 the alignment `alignof(max_align_t)`;
+ *                  `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_callocn(size_t __n, ... /*, (size_t)0 */)
@@ -20,12 +56,51 @@ libsimple_callocn(size_t __n, ... /*, (size_t)0 */)
 # define callocn libsimple_callocn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * 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   n       The number of elements to allocate, the behaviour of
+ *                  this function is unspecified for the value 0
+ * @param   m       The size of each element, the behaviour of
+ *                  this function is unspecified for the value 0
+ * @return          A unique pointer with at least the size `n * m`
+ *                  and with the alignment `alignof(max_align_t)`;
+ *                  `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2, 3), __warn_unused_result__, __returns_nonnull__)))
 void *libsimple_encalloc(int, size_t, size_t);
 #ifndef encalloc
 # define encalloc libsimple_encalloc
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, 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   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 the alignment `alignof(max_align_t)`;
+ *                  `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_envcallocn(int __st, size_t __n, va_list __ap)
 { return libsimple_envmalloczn(__st, 1, __n, __ap); }
@@ -33,6 +108,27 @@ static inline void *libsimple_envcallocn(int __st, size_t __n, va_list __ap)
 # define envcallocn libsimple_envcallocn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, 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   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 the alignment `alignof(max_align_t)`;
+ *                  `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_encallocn(int __status, size_t __n, ... /*, (size_t)0 */)
@@ -46,6 +142,23 @@ libsimple_encallocn(int __status, size_t __n, ... /*, (size_t)0 */)
 # define encallocn libsimple_encallocn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * 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   n  The number of elements to allocate, the behaviour of
+ *             this function is unspecified for the value 0
+ * @param   m  The size of each element, the behaviour of
+ *             this function is unspecified for the value 0
+ * @return     A unique pointer with at least the size `n * m`
+ *             and with the alignment `alignof(max_align_t)`;
+ *             `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(1, 2), __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_ecalloc(size_t __n, size_t __m)
 { return encalloc(libsimple_default_failure_exit, __n, __m); }
@@ -53,6 +166,27 @@ static inline void *libsimple_ecalloc(size_t __n, size_t __m)
 # define ecalloc libsimple_ecalloc
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, 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   status  The exit value for the process in case of failure
+ * @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 the alignment `alignof(max_align_t)`;
+ *                  `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_evcallocn(size_t __n, va_list __ap)
 { return libsimple_envcallocn(libsimple_default_failure_exit, __n, __ap); }
@@ -60,6 +194,27 @@ static inline void *libsimple_evcallocn(size_t __n, va_list __ap)
 # define evcallocn libsimple_evcallocn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, 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   status  The exit value for the process in case of failure
+ * @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 the alignment `alignof(max_align_t)`;
+ *                  `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_ecallocn(size_t __n, ... /*, (size_t)0 */)
diff --git a/libsimple/env.h b/libsimple/env.h
index e97c65f..dc58276 100644
--- a/libsimple/env.h
+++ b/libsimple/env.h
@@ -93,9 +93,9 @@ libsimple_putenvf(const char *__fmt, ...)
  * only the name, but this can couse problems in some programs
  * and should not done; the name however must not be empty
  * 
- * On failure, the libsimple_enprintf function is called,
+ * On failure, the `libsimple_enprintf` function is called,
  * cause the program to print an error message and exit,
- * see libsimple_enprintf for more information
+ * see `libsimple_enprintf` for more information
  * 
  * @param  status  The exit value for the process in case of failure
  * @param  fmt     Format string, see vsprintf(3)
@@ -117,9 +117,9 @@ void libsimple_envputenvf(int, const char *, va_list);
  * only the name, but this can couse problems in some programs
  * and should not done; the name however must not be empty
  * 
- * On failure, the libsimple_enprintf function is called,
+ * On failure, the `libsimple_enprintf` function is called,
  * cause the program to print an error message and exit,
- * see libsimple_enprintf for more information
+ * see `libsimple_enprintf` for more information
  * 
  * @param  status  The exit value for the process in case of failure
  * @param  fmt     Format string, see vsprintf(3)
@@ -148,9 +148,9 @@ libsimple_enputenvf(int __status, const char *__fmt, ...)
  * only the name, but this can couse problems in some programs
  * and should not done; the name however must not be empty
  * 
- * On failure, the libsimple_eprintf function is called,
+ * On failure, the `libsimple_eprintf` function is called,
  * cause the program to print an error message and exit,
- * see libsimple_eprintf for more information
+ * see `libsimple_eprintf` for more information
  * 
  * @param  fmt  Format string, see vsprintf(3)
  * @param  ap   Format arguments, see vsprintf(3)
@@ -172,9 +172,9 @@ static inline void libsimple_evputenvf(const char *__fmt, va_list __ap)
  * only the name, but this can couse problems in some programs
  * and should not done; the name however must not be empty
  * 
- * On failure, the libsimple_eprintf function is called,
+ * On failure, the `libsimple_eprintf` function is called,
  * cause the program to print an error message and exit,
- * see libsimple_eprintf for more information
+ * see `libsimple_eprintf` for more information
  * 
  * @param  fmt  Format string, see vsprintf(3)
  * @param  ap   Format arguments, see vsprintf(3)
diff --git a/libsimple/malloc.h b/libsimple/malloc.h
index feb1944..883a216 100644
--- a/libsimple/malloc.h
+++ b/libsimple/malloc.h
@@ -1,5 +1,23 @@
 /* See LICENSE file for copyright and license details. */
 
+
+/**
+ * Dynamically allocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, up to the first 0,
+ * will be used as the number of bytes to allocated
+ * 
+ * @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 the alignment `alignof(max_align_t)`;
+ *                  `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_vmallocn(size_t __n, va_list __ap)
 { return libsimple_vmalloczn(0, __n, __ap); }
@@ -7,6 +25,24 @@ static inline void *libsimple_vmallocn(size_t __n, va_list __ap)
 # define vmallocn libsimple_vmallocn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, up to the first 0,
+ * will be used as the number of bytes to allocated
+ * 
+ * @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 the alignment `alignof(max_align_t)`;
+ *                  `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_mallocn(size_t __n, ... /*, (size_t)0 */)
@@ -20,19 +56,77 @@ libsimple_mallocn(size_t __n, ... /*, (size_t)0 */)
 # define mallocn libsimple_mallocn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * 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   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 the alignment `alignof(max_align_t)`;
+ *                  `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2), __warn_unused_result__, __returns_nonnull__)))
 void *libsimple_enmalloc(int, size_t);
 #ifndef enmalloc
 # define enmalloc libsimple_enmalloc
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, 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   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 the alignment `alignof(max_align_t)`;
+ *                  `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
-static inline void *libsimple_envmallocn(int __st, size_t __n, va_list __ap)
-{ return libsimple_envmalloczn(__st, 0, __n, __ap); }
+static inline void *libsimple_envmallocn(int __status, size_t __n, va_list __ap)
+{ return libsimple_envmalloczn(__status, 0, __n, __ap); }
 #ifndef envmallocn
 # define envmallocn libsimple_envmallocn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, 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   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 the alignment `alignof(max_align_t)`;
+ *                  `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_enmallocn(int __status, size_t __n, ... /*, (size_t)0 */)
@@ -46,6 +140,21 @@ libsimple_enmallocn(int __status, size_t __n, ... /*, (size_t)0 */)
 # define enmallocn libsimple_enmallocn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * 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   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 the alignment `alignof(max_align_t)`;
+ *             `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(1), __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_emalloc(size_t __n)
 { return libsimple_enmalloc(libsimple_default_failure_exit, __n); }
@@ -53,6 +162,27 @@ static inline void *libsimple_emalloc(size_t __n)
 # define emalloc libsimple_emalloc
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, 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   status  The exit value for the process in case of failure
+ * @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 the alignment `alignof(max_align_t)`;
+ *                  `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_evmallocn(size_t __n, va_list __ap)
 { return libsimple_envmallocn(libsimple_default_failure_exit, __n, __ap); }
@@ -60,6 +190,27 @@ static inline void *libsimple_evmallocn(size_t __n, va_list __ap)
 # define evmallocn libsimple_evmallocn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments, 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   status  The exit value for the process in case of failure
+ * @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 the alignment `alignof(max_align_t)`;
+ *                  `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_emallocn(size_t __n, ... /*, (size_t)0 */)