Add DStr docs.

Small test changes

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