more dox

libfatstr/libfatstr.h

@@ -1,15 +1,34 @@
+/* #include <stdlib.h> /* size_t */
+/* These definitions aren't set in stone. */
 typedef size_t FatStr_size_t;
 typedef int FatStr_scalar_t;
 typedef FatStr_scalar_t * FatStr_vector_t;
 
+/* This definition is dependable. */
 struct FatStr{
-	FatStr_size_t a; /* allocation */
-	FatStr_size_t s; /* actual size */
+	FatStr_size_t a; /* allocation in sizeof char */
+	FatStr_size_t s; /* actual size in sizeof *v */
 	FatStr_vector_t v; /* vector */
 };
 
+/* FatStr_append
+ * - FatStr *p: object to which to append
+ * - FatStr_scalar_t c: scalar to be appended
+ * Returns NULL if the operation failed (due to malloc(3)) or if p was NULL.
+ * Otherwise returns p. */
 struct FatStr *FatStr_append(struct FatStr *p, FatStr_scalar_t c);
+
+/* FatStr_convert
+ * - FatStr *p: object to convert
+ * Returns NULL if the operation failed (due to malloc(3)) or if p was NULL.
+ * Otherwise returns a malloc(3)d char * with the current content of p, which
+ * should be free(3)d when no longer in use. */
 char *FatStr_convert(struct FatStr *p);
+
+/* FatStr_destruct
+ * - FatStr *p: object to destruct
+ * Returns NULL. */
 struct FatStr *FatStr_destruct(struct FatStr *p);
+
 struct FatStr *FatStr_initialize(struct FatStr *p);
-struct FatStr *FatStr_trimfront();
+struct FatStr *FatStr_trimfront(struct FatStr *p, size_t units);