More docs. And test put_filter

include/ucore/dstr.h

@@ -7,11 +7,15 @@
 extern "C" {
 #endif
 
-/** A dynamically managed C-string.
+/** A managed C-string, using dynalically 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.
+ *
+ * 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.
  */
 struct DStr {
     /** Length of the managed string.*/
@@ -31,12 +35,12 @@ struct DStr {
 void uc_dstr_init(struct DStr *str);
 
 /** Destroy/free the string. 
- * (Does not free str itself, only the managed resource of the str)
+ * (Frees str->str, not str itself)
  */
 void uc_dstr_destroy(struct DStr *str);
 
 /**
- * @return the available/unused tail bytes in the string
+ * @return the available/unused tail bytes in the string.
  */
 size_t uc_dstr_available(const struct DStr *str);
 
@@ -60,7 +64,7 @@ void uc_dstr_terminate(struct DStr *str);
  */
 char *uc_dstr_str(struct DStr *str);
 
-/** reserve len bytes for appending to the dstr
+/** Reserve len bytes for appending to the dstr
  *  you must fill in a string in the 0-len range of
  *  the returned pointer.
  *
@@ -90,16 +94,18 @@ 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.
+/* Make the DStr take ownership of the given dynamically allocated string.
  * Any existing string in the DStr is freed.
  */
 void uc_dstr_own(struct DStr *str, char *s);
@@ -112,10 +118,11 @@ void uc_dstr_own(struct DStr *str, char *s);
  */
 char *uc_dstr_steal(struct DStr *str);
 
-/** Swap the A and B dstr */
+/** Swap the A and B DStr */
 void uc_str_swap(struct DStr *a, struct DStr *b);
 
 /** Replace all occurences in the DStr
+ * (This may be used to replace any embedded nul bytes too)
  *
  * @param f char to find
  * @param r char to replace with