From 045d7c2463537129f40f3d99f406c537904e3b81 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nils=20O=2E=20Sel=C3=A5sdal?= <noselasd@fiane.dyndns.org>
Date: Mon, 15 Sep 2014 21:13:43 +0200
Subject: [PATCH] Improve doxygen comments

---
 include/ucore/dstr.h   | 21 ++++++++++++++-------
 include/ucore/strvec.h |  3 ++-
 include/ucore/timers.h |  2 +-
 test/test_dstr.c       |  2 +-
 4 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/include/ucore/dstr.h b/include/ucore/dstr.h
index 1ee79ee..c1295a6 100644
--- a/include/ucore/dstr.h
+++ b/include/ucore/dstr.h
@@ -8,16 +8,22 @@
 extern "C" {
 #endif
 
-/** A managed C-string, using dynamically allocated memory for the string.
+/**@file 
+ * A managed C-string, using dynamically allocated memory for the 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.
+ * The .str member might not always be nul terminated, and should not be 
+ * accessed directly. Instead use uc_dstr_str() to retreive the managed string
+ * which will always ensure the string is nul terminated
  *
- * Normally, let the DSTR manage the nul terminator as  manually adding 
+ * Normally, let the DSTR manage the nul terminator as manually adding 
  * a nul byte and potintially adding more data to the DStr would append 
  * it after that nul terminator.
  */
+
+/** Dynamic string struct. The user is responsible for managing
+ * the struct Dstr memory, and the uc_dstr_ functions will manage
+ * the memory held in .str.
+ */
 struct DStr {
     /** Length of the managed string.*/
     size_t len;
@@ -27,10 +33,11 @@ struct DStr {
     char *str;
 };
 
-#define UC_DSTR_STATIC_INIT {0, 0, NULL}
+#define UC_DSTR_INITIALIZER {0, 0, NULL}
 
 /** Initialize a DStr.
  * Note that str->str will be NULL after initialization.
+ * (However uc_dstr_str() will return a valid (empty) string.
  *
  */
 void uc_dstr_init(struct DStr *str);
@@ -94,7 +101,7 @@ void uc_dstr_terminate(struct DStr *str);
 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
+ *  you must copy characters to all bytes in the [0-len) range of
  *  the returned pointer.
  *
  * @param len bytes to reseve
diff --git a/include/ucore/strvec.h b/include/ucore/strvec.h
index f4be722..4bbe887 100644
--- a/include/ucore/strvec.h
+++ b/include/ucore/strvec.h
@@ -82,7 +82,8 @@ void uc_strv_clear(struct UCStrv *strv);
 
 /**
  * free all elements as well as the underlying array, the UCStrv is
- * unusable after this call
+ * unusable after this call until it is initialized again.
+ * (strv itself is not free'd)
  *
  * @param strv UCStrv to destroy
  */
diff --git a/include/ucore/timers.h b/include/ucore/timers.h
index c202cb0..ecdd2e0 100644
--- a/include/ucore/timers.h
+++ b/include/ucore/timers.h
@@ -152,5 +152,5 @@ int uc_timers_run(struct UCTimers *timers);
 }
 #endif
 
-/** @{ (addtogroup) */
+/** @} (addtogroup) */
 #endif
diff --git a/test/test_dstr.c b/test/test_dstr.c
index ff9cc33..f30a0a4 100644
--- a/test/test_dstr.c
+++ b/test/test_dstr.c
@@ -85,7 +85,7 @@ START_TEST (test_dstr_own_steal)
 END_TEST
 
 START_TEST (test_dstr_trim)
-    struct DStr str = UC_DSTR_STATIC_INIT;
+    struct DStr str = UC_DSTR_INITIALIZER;
 
     uc_dstr_append_str(&str, " \t  \nHello !\r\n");
     uc_dstr_trim(&str);