Better docstrings and example driver

driver.c

@@ -13,14 +13,17 @@ main(void)
   struct RingBuf rb;
   rb_init(&rb, 10, malloc, sizeof(int));
 
-  int data = 5;
+  int arr[] = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
 
-  rb_push_back(&rb, &data, memcpy);
+  int ok = WriteOk; // Assume we can write
+  for(int i = 0; i < 10 && ok == WriteOk; i++) {
+    ok = rb_push_back(&rb, &arr[i], memcpy);
+  }
 
   int d;
-  rb_pop_front(&rb, &d);
-
+  while(rb_pop_front(&rb, &d) == ReadOk) {
     printf("Data: %d\n", d);
+  }
 
   rb_destroy(&rb, free);
 

ringbuf.h

@@ -6,38 +6,60 @@
 #define rb_size_t int
 #endif
 
-/** Signatures of generic functions */
+/** Signatures of allocators */
 typedef void *(*ALLOC_T)(rb_size_t);
+
+/** Signature of memcpy */
 typedef void *(*MEMCPY_T)(void *, const void *, rb_size_t);
 
 /**
- * Ring buffer, also known as circular buffer.
+ * @brief Ring buffer, also known as circular buffer.
  */
 struct RingBuf {
-  rb_size_t struct_size; /* Size of the struct */
-  rb_size_t capacity;    /* The physical capacity of the entire ringbuf */
-  rb_size_t count;       /* The number of elements in the buffer */
-  void     *write_head;  /* Address of the write head */
-  void     *read_head;   /* Address of the read head */
-  void     *buffer;      /* The actual data */
-  void     *buffer_end;  /* The end of the buffer */
+  rb_size_t struct_size; /** Size of the struct */
+  rb_size_t capacity;    /** The physical capacity of the entire ringbuf */
+  rb_size_t count;       /** The number of elements in the buffer */
+  void     *write_head;  /** Address of the write head */
+  void     *read_head;   /** Address of the read head */
+  void     *buffer;      /** The actual data */
+  void     *buffer_end;  /** The end of the buffer */
 } __attribute__((packed));
 
-// TODO: Perhaps unify these to RBResult?
-
 enum WriteResult { Full, WriteOk }; /** Result of a write */
 enum ReadResult { Empty, ReadOk };  /** Result of a read */
 
-/** Initialize the ring buffer */
-void rb_init(struct RingBuf *rb, rb_size_t capacity, void *(*alloc)(rb_size_t),
+/**
+ * @brief Initialize the ring buffer
+ * @param rb The ring buffer to initialize
+ * @param capacity The capacity of the ring buffer
+ * @param alloc The allocator function
+ * @param struct_size The size of the struct
+ * @return void
+ */
+void rb_init(struct RingBuf *rb, rb_size_t capacity, ALLOC_T alloc,
              rb_size_t struct_size);
 
-/** Insert data to the ring buffer */
+/**
+ * @brief Insert data to the ring buffer
+ * @param rb The ring buffer
+ * @param item The item to insert
+ * @param memcpy_fn The memcpy function
+ * @return WriteResult
+ */
 enum WriteResult rb_push_back(struct RingBuf *rb, const void *item,
                               MEMCPY_T memcpy_fn);
 
-/** Read data from the ring buffer */
+/**
+ * @brief Read data from the ring buffer
+ * @param rb The ring buffer
+ * @param item The item to read into
+ * @return ReadResult
+ */
 enum ReadResult rb_pop_front(struct RingBuf *rb, void *item);
 
-/** Free the ring buffer */
+/**
+ * @brief Free the ring buffer
+ * @param rb The ring buffer
+ * @param free The free function
+ */
 void rb_destroy(struct RingBuf *rb, void(free)());