darray: Clarify some documentation/comments

1 files changed, 18 insertions, 15 deletions

diff --git a/darray.h b/darray.h
index 22e4c68..6ab8199 100644
--- a/darray.h
+++ b/darray.h
@@ -17,27 +17,30 @@
 /**
  * A dynamic array library.
  *
- *     int ret = 0;
- *     int *array = NULL;
+ * darrays are represented by a simple pointer to the array element type, like
+ * any other array.  Behind the scenes, the capacity and current length of the
+ * array are stored along with it.  NULL is a valid way to initialize an empty
+ * darray:
  *
- *     int e = 1;
- *     if (DARRAY_PUSH(&array, &e) != 0) {
- *             goto fail;
- *     }
+ *     int *darray = NULL;
+ *
+ * To append an element to a darray, use the DARRAY_PUSH macro:
  *
- *     e = 2;
- *     if (DARRAY_PUSH(&array, &e) != 0) {
- *             goto fail;
+ *     int e = 42;
+ *     if (DARRAY_PUSH(&darray, &e) != 0) {
+ *             // Report the error...
  *     }
  *
- *     for (size_t i = 0; i < darray_length(array); ++i) {
- *             assert(array[i] == i + 1);
+ * The length can be retrieved by darray_length().  Iterating over the array
+ * works like normal arrays:
+ *
+ *     for (size_t i = 0; i < darray_length(darray); ++i) {
+ *             printf("%d\n", darray[i]);
  *     }
  *
- *     ret = 0;
- *     fail:
- *     darray_free(array);
- *     return ret;
+ * To free a darray, use darray_free():
+ *
+ *     darray_free(darray);
  */
 
 #ifndef BFS_DARRAY_H