More header file documentation

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

18 files changed, 475 insertions, 66 deletions

diff --git a/libsimple/aligned_alloc.h b/libsimple/aligned_alloc.h
index 8e7d66f..6155c7d 100644
--- a/libsimple/aligned_alloc.h
+++ b/libsimple/aligned_alloc.h
@@ -1,5 +1,10 @@
 /* See LICENSE file for copyright and license details. */
 
+/*
+ * Alignment must be a power of 2.
+ * Allocation size must be a mutiple of the alignment.
+ */
+
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_align__(1), __warn_unused_result__)))
 static inline void *libsimple_valigned_allocn(size_t __alignment, size_t __n, va_list __ap)
 { return libsimple_valigned_alloczn(0, __alignment, __n, __ap); }
diff --git a/libsimple/aligned_allocz.h b/libsimple/aligned_allocz.h
index f34a015..1c81697 100644
--- a/libsimple/aligned_allocz.h
+++ b/libsimple/aligned_allocz.h
@@ -1,5 +1,10 @@
 /* See LICENSE file for copyright and license details. */
 
+/*
+ * Alignment must be a power of 2.
+ * Allocation size must be a mutiple of the alignment.
+ */
+
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_align__(2), __warn_unused_result__)))
 void *libsimple_valigned_alloczn(int, size_t, size_t, va_list);
 #ifndef valigned_alloczn
diff --git a/libsimple/aligned_memdup.h b/libsimple/aligned_memdup.h
index 6555280..d2fa91f 100644
--- a/libsimple/aligned_memdup.h
+++ b/libsimple/aligned_memdup.h
@@ -46,7 +46,7 @@ void *libsimple_aligned_memdup(const void *, size_t, size_t);
 
 
 /**
- * Version of `libsimple_aligned_memdup` that calles `libsimple_enprintf` on error
+ * Version of `libsimple_aligned_memdup` that calls `libsimple_enprintf` on error
  * 
  * @param   status     Exit value in case of failure
  * @param   s          The bytes to copy
@@ -62,7 +62,7 @@ void *libsimple_enaligned_memdup(int, const void *, size_t, size_t);
 
 
 /**
- * Version of `libsimple_aligned_memdup` that calles `libsimple_eprintf` on error
+ * Version of `libsimple_aligned_memdup` that calls `libsimple_eprintf` on error
  * 
  * @param   s          The bytes to copy
  * @param   alignment  The alignment of the returned pointer
diff --git a/libsimple/calloc.h b/libsimple/calloc.h
index 2820d02..7b373e9 100644
--- a/libsimple/calloc.h
+++ b/libsimple/calloc.h
@@ -71,8 +71,7 @@ libsimple_callocn(size_t __n, ... /*, (size_t)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
+ *                  and with the alignment `alignof(max_align_t)`
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2, 3), __warn_unused_result__, __returns_nonnull__)))
 void *libsimple_encalloc(int, size_t, size_t);
@@ -85,8 +84,8 @@ void *libsimple_encalloc(int, size_t, size_t);
  * 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
+ * The product of all arguments except `status`, 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,
@@ -98,12 +97,11 @@ void *libsimple_encalloc(int, size_t, size_t);
  *                  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
+ *                  and with the alignment `alignof(max_align_t)`
  */
 _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); }
+static inline void *libsimple_envcallocn(int __status, size_t __n, va_list __ap)
+{ return libsimple_envmalloczn(__status, 1, __n, __ap); }
 #ifndef envcallocn
 # define envcallocn libsimple_envcallocn
 #endif
@@ -113,8 +111,8 @@ static inline void *libsimple_envcallocn(int __st, size_t __n, va_list __ap)
  * 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
+ * The product of all arguments except `status`, 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,
@@ -126,8 +124,7 @@ static inline void *libsimple_envcallocn(int __st, size_t __n, va_list __ap)
  *                  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
+ *                  and with the alignment `alignof(max_align_t)`
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
@@ -156,8 +153,7 @@ libsimple_encallocn(int __status, size_t __n, ... /*, (size_t)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
+ *             and with the alignment `alignof(max_align_t)`
  */
 _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)
@@ -178,14 +174,12 @@ static inline void *libsimple_ecalloc(size_t __n, size_t __m)
  * 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
+ * @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)`
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_evcallocn(size_t __n, va_list __ap)
@@ -206,14 +200,12 @@ static inline void *libsimple_evcallocn(size_t __n, va_list __ap)
  * 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
+ * @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)`
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
diff --git a/libsimple/malloc.h b/libsimple/malloc.h
index 883a216..b57f81f 100644
--- a/libsimple/malloc.h
+++ b/libsimple/malloc.h
@@ -69,8 +69,7 @@ libsimple_mallocn(size_t __n, ... /*, (size_t)0 */)
  * @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
+ *                  and with the alignment `alignof(max_align_t)`
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2), __warn_unused_result__, __returns_nonnull__)))
 void *libsimple_enmalloc(int, size_t);
@@ -83,8 +82,8 @@ void *libsimple_enmalloc(int, size_t);
  * 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
+ * The product of all arguments except `status`, 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,
@@ -96,8 +95,7 @@ void *libsimple_enmalloc(int, size_t);
  *                  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
+ *                  and with the alignment `alignof(max_align_t)`
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_envmallocn(int __status, size_t __n, va_list __ap)
@@ -111,8 +109,8 @@ static inline void *libsimple_envmallocn(int __status, size_t __n, va_list __ap)
  * 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
+ * The product of all arguments except `status`, 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,
@@ -124,8 +122,7 @@ static inline void *libsimple_envmallocn(int __status, size_t __n, va_list __ap)
  *                  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
+ *                  and with the alignment `alignof(max_align_t)`
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
@@ -152,8 +149,7 @@ libsimple_enmallocn(int __status, size_t __n, ... /*, (size_t)0 */)
  * @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
+ *             and with the alignment `alignof(max_align_t)`
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(1), __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_emalloc(size_t __n)
@@ -174,14 +170,12 @@ static inline void *libsimple_emalloc(size_t __n)
  * 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
+ * @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)`
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_evmallocn(size_t __n, va_list __ap)
@@ -202,14 +196,12 @@ static inline void *libsimple_evmallocn(size_t __n, va_list __ap)
  * 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
+ * @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)`
  */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
diff --git a/libsimple/mallocz.h b/libsimple/mallocz.h
index 80b2ef1..2bbd607 100644
--- a/libsimple/mallocz.h
+++ b/libsimple/mallocz.h
@@ -1,18 +1,54 @@
 /* See LICENSE file for copyright and license details. */
 
+
+/* Properly declared elsewhere { */
+
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2, 3), __warn_unused_result__, __returns_nonnull__)))
 void *libsimple_encalloc(int, size_t, size_t);
 
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2), __warn_unused_result__, __returns_nonnull__)))
 void *libsimple_enmalloc(int, size_t);
 
+/* } */
+
 
+/**
+ * Dynamically allocates heap allocated, optinally initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * 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 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__)))
 void *libsimple_vmalloczn(int, size_t, va_list);
 #ifndef vmalloczn
 # define vmalloczn libsimple_vmalloczn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optinally initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * @param   clear   Non-zero if the memory should be initialised
+ * @param   n       Th number of bytes to allocate
+ * @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__, __alloc_size__(2), __warn_unused_result__)))
 static inline void *libsimple_mallocz(int __clear, size_t __n)
 { return __clear ? calloc(1, __n) : malloc(__n); }
@@ -20,6 +56,25 @@ static inline void *libsimple_mallocz(int __clear, size_t __n)
 # define mallocz libsimple_mallocz
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optinally initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * 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 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_malloczn(int __clear, size_t __n, ... /*, (size_t)0 */)
@@ -33,6 +88,21 @@ libsimple_malloczn(int __clear, size_t __n, ... /*, (size_t)0 */)
 # define malloczn libsimple_malloczn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optinally 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   clear   Non-zero if the memory should be initialised
+ * @param   n       Th number of bytes to allocate
+ * @return          A unique pointer with at least the specified size
+ *                  and with the alignment `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(3), __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_enmallocz(int __status, int __clear, size_t __n)
 { return __clear ? libsimple_encalloc(__status, 1, __n) : libsimple_enmalloc(__status, __n); }
@@ -40,12 +110,56 @@ static inline void *libsimple_enmallocz(int __status, int __clear, size_t __n)
 # define enmallocz libsimple_enmallocz
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optinally initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments except `clear` and `status`,
+ * 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 the alignment `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 void *libsimple_envmalloczn(int, int, size_t, va_list);
 #ifndef envmalloczn
 # define envmalloczn libsimple_envmalloczn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optinally initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * The product of all arguments except `clear` and `status`,
+ * 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 the alignment `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_enmalloczn(int __status, int __clear, size_t __n, ... /*, (size_t)0 */)
@@ -59,6 +173,20 @@ libsimple_enmalloczn(int __status, int __clear, size_t __n, ... /*, (size_t)0 */
 # define enmalloczn libsimple_enmalloczn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optinally 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   clear  Non-zero if the memory should be initialised
+ * @param   n      Th number of bytes to allocate
+ * @return         A unique pointer with at least the specified size
+ *                 and with the alignment `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2), __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_emallocz(int __clear, size_t __n)
 { return libsimple_enmallocz(libsimple_default_failure_exit, __clear, __n); }
@@ -66,6 +194,26 @@ static inline void *libsimple_emallocz(int __clear, size_t __n)
 # define emallocz libsimple_emallocz
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optinally initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * 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 the alignment `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_evmalloczn(int __clear, size_t __n, va_list __ap)
 { return libsimple_envmalloczn(libsimple_default_failure_exit, __clear, __n, __ap); }
@@ -73,6 +221,26 @@ static inline void *libsimple_evmalloczn(int __clear, size_t __n, va_list __ap)
 # define evmalloczn libsimple_evmalloczn
 #endif
 
+
+/**
+ * Dynamically allocates heap allocated, optinally initialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * 
+ * 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 the alignment `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_emalloczn(int __clear, size_t __n, ... /*, (size_t)0 */)
diff --git a/libsimple/memalign.h b/libsimple/memalign.h
index 046edd4..466de3e 100644
--- a/libsimple/memalign.h
+++ b/libsimple/memalign.h
@@ -1,5 +1,9 @@
 /* See LICENSE file for copyright and license details. */
 
+/*
+ * Alignment must be a power of 2.
+ */
+
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_align__(1), __warn_unused_result__)))
 static inline void *libsimple_vmemalignn(size_t __alignment, size_t __n, va_list __ap)
 { return libsimple_vmemalignzn(0, __alignment, __n, __ap); }
diff --git a/libsimple/memalignz.h b/libsimple/memalignz.h
index 8a20295..4b47d0e 100644
--- a/libsimple/memalignz.h
+++ b/libsimple/memalignz.h
@@ -1,5 +1,9 @@
 /* See LICENSE file for copyright and license details. */
 
+/*
+ * Alignment must be a power of 2.
+ */
+
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_align__(2), __warn_unused_result__)))
 static inline void *
 libsimple_vmemalignzn(int __clear, size_t __alignment, size_t __n, va_list __ap) /* TODO test ([v]memalign[z]n) */
diff --git a/libsimple/memdup.h b/libsimple/memdup.h
index b7f2d6b..ce84f6b 100644
--- a/libsimple/memdup.h
+++ b/libsimple/memdup.h
@@ -37,7 +37,7 @@ void *libsimple_memdup(const void *, size_t);
 
 
 /**
- * Version of `libsimple_memdup` that calles `libsimple_enprintf` on error
+ * Version of `libsimple_memdup` that calls `libsimple_enprintf` on error
  * 
  * @param   status  Exit value in case of failure
  * @param   s       The bytes to copy
@@ -52,7 +52,7 @@ void *libsimple_enmemdup(int, const void *, size_t);
 
 
 /**
- * Version of `libsimple_memdup` that calles `libsimple_eprintf` on error
+ * Version of `libsimple_memdup` that calls `libsimple_eprintf` on error
  * 
  * @param   s  The bytes to copy
  * @param   n  The number of bytes to copy
diff --git a/libsimple/posix_memalign.h b/libsimple/posix_memalign.h
index dfe7a53..5443418 100644
--- a/libsimple/posix_memalign.h
+++ b/libsimple/posix_memalign.h
@@ -1,5 +1,9 @@
 /* See LICENSE file for copyright and license details. */
 
+/*
+ * Alignment must be a power of 2 and a multiple of `sizeof(void *)`.
+ */
+
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__(1))))
 static inline int libsimple_vposix_memalignn(void **__memptr, size_t __alignment, size_t __n, va_list __ap)
 { return libsimple_vposix_memalignzn(__memptr, 0, __alignment, __n, __ap); }
diff --git a/libsimple/posix_memalignz.h b/libsimple/posix_memalignz.h
index 94fc82c..2bbd310 100644
--- a/libsimple/posix_memalignz.h
+++ b/libsimple/posix_memalignz.h
@@ -1,5 +1,9 @@
 /* See LICENSE file for copyright and license details. */
 
+/*
+ * Alignment must be a power of 2 and a multiple of `sizeof(void *)`.
+ */
+
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__(1))))
 int libsimple_vposix_memalignzn(void **, int, size_t, size_t, va_list);
 #ifndef vposix_memalignzn
diff --git a/libsimple/pvalloc.h b/libsimple/pvalloc.h
index 876366b..dfd7b31 100644
--- a/libsimple/pvalloc.h
+++ b/libsimple/pvalloc.h
@@ -1,5 +1,10 @@
 /* See LICENSE file for copyright and license details. */
 
+/*
+ * The alignment will be the page size.
+ * The allocation size is rounded up to the next multiple of the alignment.
+ */
+
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__)))
 static inline void *libsimple_vpvallocn(size_t __n, va_list __ap)
 { return libsimple_vpvalloczn(0, __n, __ap); }
diff --git a/libsimple/pvallocz.h b/libsimple/pvallocz.h
index f1e58ed..2fc628d 100644
--- a/libsimple/pvallocz.h
+++ b/libsimple/pvallocz.h
@@ -1,5 +1,10 @@
 /* See LICENSE file for copyright and license details. */
 
+/*
+ * The alignment will be the page size.
+ * The allocation size is rounded up to the next multiple of the alignment.
+ */
+
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__)))
 static inline void *
 libsimple_vpvalloczn(int __clear, size_t __n, va_list __ap) /* TODO test ([v]pvalloc[z]n) */
diff --git a/libsimple/realloc.h b/libsimple/realloc.h
index 3e2fece..8ece86d 100644
--- a/libsimple/realloc.h
+++ b/libsimple/realloc.h
@@ -1,11 +1,63 @@
 /* See LICENSE file for copyright and license details. */
 
+
+/**
+ * Dynamically reallocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * as the new alignment
+ * 
+ * The product of all arguments, up to the first 0,
+ * will be used as the number of bytes to allocated
+ * 
+ * On success, either `ptr` is returned, or a new non-null
+ * pointer is returned with the same content (truncated to
+ * `n` bytes if size shrunk), in which case `ptr` is
+ * deallocated. On failure `ptr` is still valid. If `ptr`
+ * is `NULL` a new allocation is made.
+ * 
+ * @param   ptr     Pointer to reallocated, `NULL` for a new allocation
+ * @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          Either `ptr` or 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__((__warn_unused_result__)))
 void *libsimple_vreallocn(void *, size_t, va_list);
 #ifndef vreallocn
 # define vreallocn libsimple_vreallocn
 #endif
 
+
+/**
+ * Dynamically reallocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * as the new alignment
+ * 
+ * The product of all arguments, up to the first 0,
+ * will be used as the number of bytes to allocated
+ * 
+ * On success, either `ptr` is returned, or a new non-null
+ * pointer is returned with the same content (truncated to
+ * `n` bytes if size shrunk), in which case `ptr` is
+ * deallocated. On failure `ptr` is still valid. If `ptr`
+ * is `NULL` a new allocation is made.
+ * 
+ * @param   ptr     Pointer to reallocated, `NULL` for a new allocation
+ * @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          Either `ptr` or 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__((__warn_unused_result__)))
 static inline void *
 libsimple_reallocn(void *__ptr, size_t __n, ... /*, (size_t)0 */)
@@ -19,18 +71,100 @@ libsimple_reallocn(void *__ptr, size_t __n, ... /*, (size_t)0 */)
 # define reallocn libsimple_reallocn
 #endif
 
+
+/**
+ * Dynamically reallocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * as the new alignment
+ * 
+ * On success, either `ptr` is returned, or a new non-null
+ * pointer is returned with the same content (truncated to
+ * `n` bytes if size shrunk), in which case `ptr` is
+ * deallocated. On failure `ptr` is still valid. If `ptr`
+ * is `NULL` a new allocation is made.
+ * 
+ * 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   ptr     Pointer to reallocated, `NULL` for a new allocation
+ * @param   n       The number of bytes to allocate, the behaviour of
+ *                  this function is unspecified for the value 0
+ * @return          Either `ptr` or a unique pointer with at least
+ *                  the specified size and with the alignment
+ *                  `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_size__(3), __warn_unused_result__, __returns_nonnull__)))
 void *libsimple_enrealloc(int, void *, size_t);
 #ifndef enrealloc
 # define enrealloc libsimple_enrealloc
 #endif
 
+
+/**
+ * Dynamically reallocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * as the new alignment
+ * 
+ * The product of all arguments except `status`, up to the
+ * first 0, will be used as the number of bytes to allocated
+ * 
+ * On success, either `ptr` is returned, or a new non-null
+ * pointer is returned with the same content (truncated to
+ * `n` bytes if size shrunk), in which case `ptr` is
+ * deallocated. On failure `ptr` is still valid. If `ptr`
+ * is `NULL` a new allocation is made.
+ * 
+ * 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   ptr     Pointer to reallocated, `NULL` for a new allocation
+ * @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          Either `ptr` or a unique pointer with at least
+ *                  the specified size and with the alignment
+ *                  `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__)))
 void *libsimple_envreallocn(int, void *, size_t, va_list);
 #ifndef envreallocn
 # define envreallocn libsimple_envreallocn
 #endif
 
+
+/**
+ * Dynamically reallocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * as the new alignment
+ * 
+ * The product of all arguments except `status`, up to the
+ * first 0, will be used as the number of bytes to allocated
+ * 
+ * On success, either `ptr` is returned, or a new non-null
+ * pointer is returned with the same content (truncated to
+ * `n` bytes if size shrunk), in which case `ptr` is
+ * deallocated. On failure `ptr` is still valid. If `ptr`
+ * is `NULL` a new allocation is made.
+ * 
+ * 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   ptr     Pointer to reallocated, `NULL` for a new allocation
+ * @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          Either `ptr` or a unique pointer with at least
+ *                  the specified size and with the alignment
+ *                  `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_enreallocn(int __status, void *__ptr, size_t __n, ... /*, (size_t)0 */)
@@ -44,6 +178,29 @@ libsimple_enreallocn(int __status, void *__ptr, size_t __n, ... /*, (size_t)0 */
 # define enreallocn libsimple_enreallocn
 #endif
 
+
+/**
+ * Dynamically reallocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * as the new alignment
+ * 
+ * On success, either `ptr` is returned, or a new non-null
+ * pointer is returned with the same content (truncated to
+ * `n` bytes if size shrunk), in which case `ptr` is
+ * deallocated. On failure `ptr` is still valid. If `ptr`
+ * is `NULL` a new allocation is made.
+ * 
+ * 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   ptr  Pointer to reallocated, `NULL` for a new allocation
+ * @param   n    The number of bytes to allocate, the behaviour of
+ *               this function is unspecified for the value 0
+ * @return       Either `ptr` or a unique pointer with at least
+ *               the specified size and with the alignment
+ *               `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_size__(2), __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_erealloc(void *__ptr, size_t __n)
 { return enrealloc(libsimple_default_failure_exit, __ptr, __n); }
@@ -51,6 +208,34 @@ static inline void *libsimple_erealloc(void *__ptr, size_t __n)
 # define erealloc libsimple_erealloc
 #endif
 
+
+/**
+ * Dynamically reallocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * as the new alignment
+ * 
+ * The product of all arguments, up to the first 0,
+ * will be used as the number of bytes to allocated
+ * 
+ * On success, either `ptr` is returned, or a new non-null
+ * pointer is returned with the same content (truncated to
+ * `n` bytes if size shrunk), in which case `ptr` is
+ * deallocated. On failure `ptr` is still valid. If `ptr`
+ * is `NULL` a new allocation is made.
+ * 
+ * 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   ptr  Pointer to reallocated, `NULL` for a new allocation
+ * @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       Either `ptr` or a unique pointer with at least
+ *               the specified size and with the alignment
+ *               `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_evreallocn(void *__ptr, size_t __n, va_list __ap)
 { return libsimple_envreallocn(libsimple_default_failure_exit, __ptr, __n, __ap); }
@@ -58,6 +243,34 @@ static inline void *libsimple_evreallocn(void *__ptr, size_t __n, va_list __ap)
 # define evreallocn libsimple_evreallocn
 #endif
 
+
+/**
+ * Dynamically reallocates heap allocated, uninitialised,
+ * memory with default alignment (`alignof(max_align_t)`)
+ * as the new alignment
+ * 
+ * The product of all arguments, up to the first 0,
+ * will be used as the number of bytes to allocated
+ * 
+ * On success, either `ptr` is returned, or a new non-null
+ * pointer is returned with the same content (truncated to
+ * `n` bytes if size shrunk), in which case `ptr` is
+ * deallocated. On failure `ptr` is still valid. If `ptr`
+ * is `NULL` a new allocation is made.
+ * 
+ * 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   ptr  Pointer to reallocated, `NULL` for a new allocation
+ * @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       Either `ptr` or a unique pointer with at least
+ *               the specified size and with the alignment
+ *               `alignof(max_align_t)`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__)))
 static inline void *
 libsimple_ereallocn(void *__ptr, size_t __n, ... /*, (size_t)0 */)
diff --git a/libsimple/strdup.h b/libsimple/strdup.h
index 9f069f4..33994e3 100644
--- a/libsimple/strdup.h
+++ b/libsimple/strdup.h
@@ -22,7 +22,7 @@
 
 
 /**
- * Version of strdup(3) that calles `libsimple_enprintf` on error
+ * Version of strdup(3) that calls `libsimple_enprintf` on error
  * 
  * @param   status  Exit value in case of failure
  * @param   s       The string to copy
@@ -36,7 +36,7 @@ char *libsimple_enstrdup(int, const char *);
 
 
 /**
- * Version of strdup(3) that calles `libsimple_eprintf` on error
+ * Version of strdup(3) that calls `libsimple_eprintf` on error
  * 
  * @param   s  The string to copy
  * @return     Duplicate of `s`
diff --git a/libsimple/strndup.h b/libsimple/strndup.h
index 4a7dc22..2b5bbd0 100644
--- a/libsimple/strndup.h
+++ b/libsimple/strndup.h
@@ -26,7 +26,7 @@
 
 
 /**
- * Version of strndup(3) that calles `libsimple_enprintf` on error
+ * Version of strndup(3) that calls `libsimple_enprintf` on error
  * 
  * @param   status  Exit value in case of failure
  * @param   s       The string to copy
@@ -41,7 +41,7 @@ char *libsimple_enstrndup(int, const char *, size_t);
 
 
 /**
- * Version of strndup(3) that calles `libsimple_eprintf` on error
+ * Version of strndup(3) that calls `libsimple_eprintf` on error
  * 
  * @param   s  The string to copy
  * @param   n  The maximum number of bytes to copy
diff --git a/libsimple/valloc.h b/libsimple/valloc.h
index 02d301a..6f9d57b 100644
--- a/libsimple/valloc.h
+++ b/libsimple/valloc.h
@@ -1,5 +1,9 @@
 /* See LICENSE file for copyright and license details. */
 
+/*
+ * The alignment will be the page size.
+ */
+
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__)))
 static inline void *libsimple_vvallocn(size_t __n, va_list __ap)
 { return libsimple_vvalloczn(0, __n, __ap); }
diff --git a/libsimple/vallocz.h b/libsimple/vallocz.h
index d32598e..2831cf8 100644
--- a/libsimple/vallocz.h
+++ b/libsimple/vallocz.h
@@ -1,5 +1,9 @@
 /* See LICENSE file for copyright and license details. */
 
+/*
+ * The alignment will be the page size.
+ */
+
 _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) */