Add docs for memory functionswget2

* libwget/mem.c: Add docs
* docs/Makefile.am: Add rule for man pages
* include/libwget.h.in: Cosmetic adjustments

3 files changed, 59 insertions, 17 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index f96356d4..66307324 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -8,7 +8,8 @@ man3_MANS =\
  $(builddir)/man/man3/libwget-random.3\
  $(builddir)/man/man3/libwget-xalloc.3\
  $(builddir)/man/man3/libwget-printf.3\
- $(builddir)/man/man3/libwget-md5.3
+ $(builddir)/man/man3/libwget-md5.3\
+ $(builddir)/man/man3/libwget-mem.3
 
 $(man3_MANS): doxy.stamp
 
diff --git a/include/libwget.h.in b/include/libwget.h.in
index 2c270a36..a8e2b016 100644
--- a/include/libwget.h.in
+++ b/include/libwget.h.in
@@ -396,11 +396,11 @@ void
  */
 
 void *
-	wget_memdup(const void *s, size_t n) G_GNUC_WGET_ALLOC_SIZE(2) LIBWGET_EXPORT;
+	wget_memdup(const void *m, size_t n) G_GNUC_WGET_ALLOC_SIZE(2) LIBWGET_EXPORT;
 char *
 	wget_strdup(const char *s) G_GNUC_WGET_MALLOC LIBWGET_EXPORT;
 char *
-	wget_strmemdup(const void *s, size_t n) G_GNUC_WGET_ALLOC_SIZE(2) LIBWGET_EXPORT;
+	wget_strmemdup(const void *m, size_t n) G_GNUC_WGET_ALLOC_SIZE(2) LIBWGET_EXPORT;
 void
 	wget_strmemcpy(char *s, size_t ssize, const void *m, size_t n) G_GNUC_WGET_NONNULL_ALL LIBWGET_EXPORT;
 
diff --git a/libwget/mem.c b/libwget/mem.c
index 72c4666f..83a61329 100644
--- a/libwget/mem.c
+++ b/libwget/mem.c
@@ -34,35 +34,74 @@
 #include <libwget.h>
 #include "private.h"
 
-// strdup which accepts NULL values
+/**
+ * \file
+ * \brief Memory functions
+ * \defgroup libwget-mem Memory functions
+ * @{
+ *
+ * This is a collections of short memory function not available in standard libraries.
+ */
 
-char *wget_strdup(const char *s)
+/**
+ * \param[in] m Memory to clone
+ * \param[in] n Length of memory
+ * \return Cloned memory
+ *
+ * Clone's the memory region \p m with length \p n.
+ * Returns NULL if \p m is NULL.
+ *
+ * You should free() the returned pointer when not needed any more.
+ */
+void *wget_memdup(const void *m, size_t n)
 {
-	return s ? strcpy(xmalloc(strlen(s) + 1), s) : NULL;
+	return m ? memcpy(xmalloc(n), m, n) : NULL;
 }
 
-// memdup sometimes comes in handy
-
-void *wget_memdup(const void *s, size_t n)
+/**
+ * \param[in] s String to clone
+ * \return Cloned string
+ *
+ * Clone's the string \p s like strdup() does.
+ * Returns NULL if \p s is NULL.
+ *
+ * You should free() the returned string when not needed any more.
+ */
+char *wget_strdup(const char *s)
 {
-	return s ? memcpy(xmalloc(n), s, n) : NULL;
+	return s ? wget_memdup(s, strlen(s) + 1) : NULL;
 }
 
-// convert memory chunk into allocated string
-
-char *wget_strmemdup(const void *s, size_t n)
+/**
+ * \param[in] m Memory to convert into string
+ * \param[in] n Length of memory
+ * \return Created string
+ *
+ * Convert the given memory region \p m with length \p n into a C string.
+ * Returns NULL if \p m is NULL.
+ *
+ * You should free() the returned string when not needed any more.
+ */
+char *wget_strmemdup(const void *m, size_t n)
 {
-	if (!s)
+	if (!m)
 		return NULL;
 
-	char *ret = memcpy(xmalloc(n + 1), s, n);
+	char *ret = memcpy(xmalloc(n + 1), m, n);
 	ret[n] = 0;
 
 	return ret;
 }
 
-// convert memory chunk to string
-
+/**
+ * \param[out] s Buffer to hold the C string output
+ * \param[in] ssize Size of the output buffer
+ * \param[in] m Memory to read from
+ * \param[in] n Length of memory
+ *
+ * Convert the given memory region \p m with length \p n into a C string at \p s.
+ * A max. of \p ssize - 1  is copied into \p s.
+ */
 void wget_strmemcpy(char *s, size_t ssize, const void *m, size_t n)
 {
 	if (n >= ssize)
@@ -71,3 +110,5 @@ void wget_strmemcpy(char *s, size_t ssize, const void *m, size_t n)
 	memcpy(s, m, n);
 	s[n] = 0;
 }
+
+/**@}*/