Improve doxygen comments

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,
+ * The .str member might not always be nul terminated, and should not be 
- * Normally, use uc_dstr_str() to retreive the managed string
+ * accessed directly. Instead use uc_dstr_str() to retreive the managed string
- * instead of accessing ->str directly.
+ * 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

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
  */

include/ucore/timers.h

@@ -152,5 +152,5 @@ int uc_timers_run(struct UCTimers *timers);
 }
 #endif
 
-/** @{ (addtogroup) */
+/** @} (addtogroup) */
 #endif

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);