Improve mbuf documentation

include/ucore/mbuf.h

@@ -24,16 +24,17 @@
   @endverbatim
  * 
  * Initially when empty, head == tail, and the length is 0. 
- * Data is added to the tail.
+ * Data can be added to the tailroom or the headroom.
+ * The data is the memory from (including) head to (excluding) tail.
  *
  * If head == bufstart, there is no headroom
  * if tail points one past the allocated space, there is no 
  * tailroom (the buffer is full)
  *
  * Conventions:
- * push - prepend data to the buffer (in the head room part)
+ * push - prepend data to the buffer in the head room part
  *        (move head to the left)
- * pull - remove data from the beginning of the message.
+ * pull - remove data from the beginning of the data
  *        (move head to the right)
  * put  - Add data to the buffer.
  *        (move tail to the right)
@@ -103,7 +104,12 @@ struct MBuf *uc_mbuf_new_inline_hr(uint32_t len, uint32_t headroom);
 /** As uc_mbuf_new_inline_hr, but without any headroom*/
 #define uc_mbuf_new_inline(len) uc_mbuf_new_inline_hr((len), 0)
 
-/** @param mbuf the mbuf to free. (passing NULL is a no-op)*/
+/** Free the memory of an mbuf and its data.
+ * If passing in NULL or an mbuf with a UC_MBUF_FL_STATIC flag,
+ * no action is taken.
+ *
+ * @param mbuf the mbuf to free.
+ */
 void uc_mbuf_free(struct MBuf *mbuf);
 
 /** Create a new mbuf, with a copy of the data from the given
@@ -117,9 +123,7 @@ struct MBuf *uc_mbuf_copy_data(struct MBuf *mbuf);
 /** Initialize an mbuf. This function is mostly used internally,
  * but can be used to e.g. create an mbuf based on a local array
  * (in which case UC_MBUF_FL_STATIC must be set), or other data 
- * whose memory is already allocated.
- *
- * The whole buffer must have len + headroom available data
+ * whose memory is already allocated. * The whole buffer must have len + headroom available data
  *
  * @param mbuf to initialise
  * @param buf start of the buffer
@@ -130,7 +134,7 @@ struct MBuf *uc_mbuf_copy_data(struct MBuf *mbuf);
 void uc_mbuf_init(struct MBuf *mbuf, uint8_t *restrict buf, uint32_t len, 
                  uint32_t headroom, uint32_t flags);
 
-/** Zero out all the data in this mbuf, including the headroom
+/** Zero out all the data in this mbuf, including the headroom and tailroom
  *
  * @param mbuf mbuf to zero out
  */