From 8749270ca4d0fe9bf184bea535629e7365d7dbe9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nils=20O=2E=20Sel=C3=A5sdal?= <noselasd@fiane.dyndns.org>
Date: Wed, 4 Dec 2013 20:32:06 +0100
Subject: [PATCH] Add DStr docs. Small test changes

---
 include/ucore/dstr.h | 68 +++++++++++++++++++++++++++++++++++++++++---
 test/test_dstr.c     |  3 +-
 2 files changed, 65 insertions(+), 6 deletions(-)

diff --git a/include/ucore/dstr.h b/include/ucore/dstr.h
index d39b8d7..1f03f61 100644
--- a/include/ucore/dstr.h
+++ b/include/ucore/dstr.h
@@ -7,13 +7,17 @@
 extern "C" {
 #endif
 
-/** A dynamic string.
- * The string might not always be nul terminated,
- * Normally, use uc_dstr_str() to manipulate the managed string
+/** A dynamically managed C-string.
+ *
+ * The .str member might not always be nul terminated,
+ * Normally, use uc_dstr_str() to retreive the managed string
  * instead of accessing ->str directly.
  */
 struct DStr {
+    /** Length of the managed string.*/
     size_t len;
+
+    //internal fields:
     size_t allocated;
     char *str;
 };
@@ -37,34 +41,90 @@ void uc_dstr_destroy(struct DStr *str);
 size_t uc_dstr_available(const struct DStr *str);
 
 /** Ensure the DStr is of at least 'len' bytes,
- * allocating room if needed. 
+ *  allocating room if needed. 
+ *
+ *  @return 0 on success (!= 0 if an allocation fail)
  */
 int uc_dstr_ensure(struct DStr *str, size_t len);
 
+/** Reset the DStr, setting its length to 0
+ */
 void uc_dstr_reset(struct DStr *str);
 
+/** nul terminate the DStr */
 void uc_dstr_terminate(struct DStr *str);
 
+/** Retreive the managed string, the returned string
+ * is always nul terminated. The DStr will still be managing
+ * the returned char *.
+ */
 char *uc_dstr_str(struct DStr *str);
 
+/** reserve len bytes for appending to the dstr
+ *  you must fill in a string in the 0-len range of
+ *  the returned pointer.
+ *
+ * @param len bytes to reseve
+ * @return poiinter to the start of the data to append
+ */
 char *uc_dstr_put(struct DStr *str, size_t len);
 
+/** Append a string, filtering out characters.
+ * e.g. pass in the ctype.h isdigit as the is_x function
+ * to append only the digits in the supplied string.
+ *
+ * @param s string to append
+ * @param is_x ctype.h compatible function to use as a filter.
+ * @return number of chars appended
+ */
 size_t uc_dstr_put_str_filter(struct DStr *str, const char *s, int (*is_x)(int c));
 
+/* Append a string of the give size.
+ * (The nul terminator is not appended) 
+ * 
+ * @param s string to append
+ * @param len bytes to append (not including the nul terminator) 
+ * @return 0 on success (!= 0 if an allocation fail)
+ */
 int uc_dstr_put_str_sz(struct DStr *str, const char *s, size_t len);
 
+/* Append a string.
+ * (The nul terminator is not appended) 
+ *  @return 0 on success (!= 0 if an allocation fail)
+ */
 int uc_dstr_put_str(struct DStr *str, const char *s);
 
+/* Append a single char.
+ *  @return 0 on success (!= 0 if an allocation fail)
+ */
 int uc_dstr_put_char(struct DStr *str, char c);
 
+/* Make the DStr take ownership of the give dynamically allocated string.
+ * Any existing string in the DStr is freed.
+ */
 void uc_dstr_own(struct DStr *str, char *s);
 
+/** Release the managed string.
+ * The caller is now responsible for managing/free'ing the returned string.
+ * The DStr is considered empty afterwards.
+ *
+ * @return The dynamically allocated string that was managed.
+ */
 char *uc_dstr_steal(struct DStr *str);
 
+/** Swap the A and B dstr */
 void uc_str_swap(struct DStr *a, struct DStr *b);
 
+/** Replace all occurences in the DStr
+ *
+ * @param f char to find
+ * @param r char to replace with
+ */
 size_t uc_dstr_replace(struct DStr *str, char f, char r);
 
+/** Remove leading and trailing spaces in the DStr
+ * Spaces are the ascii ones: " \t\r\v\t\n"
+ */
 void uc_dstr_trim(struct DStr *str);
 
 #ifdef __cplusplus
diff --git a/test/test_dstr.c b/test/test_dstr.c
index e04caf6..4e53443 100644
--- a/test/test_dstr.c
+++ b/test/test_dstr.c
@@ -65,9 +65,8 @@ START_TEST (test_dstr_own_steal)
 END_TEST
 
 START_TEST (test_dstr_trim)
-    struct DStr str;
+    struct DStr str = UC_DSTR_STATIC_INIT;
 
-    uc_dstr_init(&str);
     uc_dstr_put_str(&str, " \t  \nHello !\r\n");
     uc_dstr_trim(&str);
     ck_assert_str_eq(uc_dstr_str(&str), "Hello !");