Add doc to aligned_memdup.h, memdup.h, strdup.h, and strndup.h

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

4 files changed, 117 insertions, 0 deletions

diff --git a/libsimple/aligned_memdup.h b/libsimple/aligned_memdup.h
index 8138eb2..6555280 100644
--- a/libsimple/aligned_memdup.h
+++ b/libsimple/aligned_memdup.h
@@ -1,5 +1,14 @@
 /* See LICENSE file for copyright and license details. */
 
+
+/**
+ * Stack allocation version of `libsimple_aligned_memdup`
+ * 
+ * @param   s:const void *    The bytes to copy
+ * @param   alignment:size_t  The alignment of the returned pointer
+ * @param   n:size_t          The number of bytes to copy
+ * @return  :void *           Duplicate of `s` with automatic storage
+ */
 #if defined(__GNUC__) || defined(__clang__)
 # define libsimple_aligned_memdupa(s, alignment, n)\
 	({\
@@ -20,18 +29,46 @@
 # endif
 #endif
 
+
+/**
+ * Create a new allocation, with custom alignment, and copy bytes into it
+ * 
+ * @param   s          The bytes to copy
+ * @param   alignment  The alignment of the returned pointer
+ * @param   n          The number of bytes to copy
+ * @return             Duplicate of `s`, `NULL` on failure
+ */	
 _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_align__(2), __alloc_size__(3), __nonnull__, __warn_unused_result__)))
 void *libsimple_aligned_memdup(const void *, size_t, size_t);
 #ifndef aligned_memdup
 # define aligned_memdup libsimple_aligned_memdup
 #endif
 
+
+/**
+ * Version of `libsimple_aligned_memdup` that calles `libsimple_enprintf` on error
+ * 
+ * @param   status     Exit value in case of failure
+ * @param   s          The bytes to copy
+ * @param   alignment  The alignment of the returned pointer
+ * @param   n          The number of bytes to copy
+ * @return             Duplicate of `s`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_align__(3), __alloc_size__(4), __warn_unused_result__, __returns_nonnull__)))
 void *libsimple_enaligned_memdup(int, const void *, size_t, size_t);
 #ifndef enaligned_memdup
 # define enaligned_memdup libsimple_enaligned_memdup
 #endif
 
+
+/**
+ * Version of `libsimple_aligned_memdup` that calles `libsimple_eprintf` on error
+ * 
+ * @param   s          The bytes to copy
+ * @param   alignment  The alignment of the returned pointer
+ * @param   n          The number of bytes to copy
+ * @return             Duplicate of `s`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_align__(2), __alloc_size__(3), __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_ealigned_memdup(const void *__s, size_t __alignment, size_t __n)
 { return enaligned_memdup(libsimple_default_failure_exit, __s, __alignment, __n); }
diff --git a/libsimple/memdup.h b/libsimple/memdup.h
index 44d3a2a..b7f2d6b 100644
--- a/libsimple/memdup.h
+++ b/libsimple/memdup.h
@@ -1,5 +1,13 @@
 /* See LICENSE file for copyright and license details. */
 
+
+/**
+ * Stack allocation version of `libsimple_memdup`
+ * 
+ * @param   s:const void *  The bytes to copy
+ * @param   n:size_t        The number of bytes to copy
+ * @return  :void *         Duplicate of `s` with automatic storage
+ */
 #if defined(__GNUC__) || defined(__clang__)
 # define libsimple_memdupa(s, n)\
 	({\
@@ -13,18 +21,43 @@
 # endif
 #endif
 
+
+/**
+ * Create a new allocation and copy bytes into it
+ * 
+ * @param   s  The bytes to copy
+ * @param   n  The number of bytes to copy
+ * @return     Duplicate of `s`, `NULL` on failure
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_size__(2), __nonnull__, __warn_unused_result__)))
 void *libsimple_memdup(const void *, size_t);
 #ifndef memdup
 # define memdup libsimple_memdup
 #endif
 
+
+/**
+ * Version of `libsimple_memdup` that calles `libsimple_enprintf` on error
+ * 
+ * @param   status  Exit value in case of failure
+ * @param   s       The bytes to copy
+ * @param   n       The number of bytes to copy
+ * @return          Duplicate of `s`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_size__(3), __warn_unused_result__, __returns_nonnull__)))
 void *libsimple_enmemdup(int, const void *, size_t);
 #ifndef enmemdup
 # define enmemdup libsimple_enmemdup
 #endif
 
+
+/**
+ * Version of `libsimple_memdup` that calles `libsimple_eprintf` on error
+ * 
+ * @param   s  The bytes to copy
+ * @param   n  The number of bytes to copy
+ * @return     Duplicate of `s`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_size__(2), __warn_unused_result__, __returns_nonnull__)))
 static inline void *libsimple_ememdup(const void *__s, size_t __n)
 { return enmemdup(libsimple_default_failure_exit, __s, __n); }
diff --git a/libsimple/strdup.h b/libsimple/strdup.h
index 1397893..9f069f4 100644
--- a/libsimple/strdup.h
+++ b/libsimple/strdup.h
@@ -1,5 +1,12 @@
 /* See LICENSE file for copyright and license details. */
 
+
+/**
+ * Stack allocation version of strdup(3)
+ * 
+ * @param   s:const char *  The string to copy
+ * @return  :char *         Duplicate of `s` with automatic storage
+ */
 #if defined(__GNUC__) || defined(__clang__)
 # define libsimple_strdupa(s)\
 	({\
@@ -13,12 +20,27 @@
 # endif
 #endif
 
+
+/**
+ * Version of strdup(3) that calles `libsimple_enprintf` on error
+ * 
+ * @param   status  Exit value in case of failure
+ * @param   s       The string to copy
+ * @return          Duplicate of `s`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __assume_aligned__(1), __nonnull__, __warn_unused_result__, __returns_nonnull__)))
 char *libsimple_enstrdup(int, const char *);
 #ifndef enstrdup
 # define enstrdup libsimple_enstrdup
 #endif
 
+
+/**
+ * Version of strdup(3) that calles `libsimple_eprintf` on error
+ * 
+ * @param   s  The string to copy
+ * @return     Duplicate of `s`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __assume_aligned__(1), __nonnull__, __warn_unused_result__, __returns_nonnull__)))
 static inline char *libsimple_estrdup(const char *__s)
 { return enstrdup(libsimple_default_failure_exit, __s); }
diff --git a/libsimple/strndup.h b/libsimple/strndup.h
index 961b131..4a7dc22 100644
--- a/libsimple/strndup.h
+++ b/libsimple/strndup.h
@@ -1,5 +1,13 @@
 /* See LICENSE file for copyright and license details. */
 
+
+/**
+ * Stack allocation version of strndup(3)
+ * 
+ * @param   s:const char *  The string to copy
+ * @param   n:size_t        The maximum number of bytes to copy
+ * @return  :char *         Duplicate of `s` with automatic storage
+ */
 #if defined(__GNUC__) || defined(__clang__)
 # define libsimple_strndupa(s, n)\
 	({\
@@ -16,12 +24,29 @@
 # endif
 #endif
 
+
+/**
+ * Version of strndup(3) that calles `libsimple_enprintf` on error
+ * 
+ * @param   status  Exit value in case of failure
+ * @param   s       The string to copy
+ * @param   n       The maximum number of bytes to copy
+ * @return          Duplicate of `s`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __assume_aligned__(1), __nonnull__, __warn_unused_result__, __returns_nonnull__)))
 char *libsimple_enstrndup(int, const char *, size_t);
 #ifndef enstrndup
 # define enstrndup libsimple_enstrndup
 #endif
 
+
+/**
+ * Version of strndup(3) that calles `libsimple_eprintf` on error
+ * 
+ * @param   s  The string to copy
+ * @param   n  The maximum number of bytes to copy
+ * @return     Duplicate of `s`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __assume_aligned__(1), __nonnull__, __warn_unused_result__, __returns_nonnull__)))
 static inline char *libsimple_estrndup(const char *__s, size_t __n)
 { return enstrndup(libsimple_default_failure_exit, __s, __n); }