Document 'union buflib_data'

Change-Id: Ia98fa8e7887338d6c0b7a5795a0ae5c7a13014ba

2 files changed, 11 insertions, 8 deletions

diff --git a/firmware/buflib.c b/firmware/buflib.c
index 8d5fe1eef3..b6e5551efb 100644
--- a/firmware/buflib.c
+++ b/firmware/buflib.c
@@ -44,7 +44,7 @@
  * the buffer. The buffer is treated as an array of union buflib_data. Blocks
  * start with a length marker, which is included in their length. Free blocks
  * are marked by negative length. Allocated blocks have a positiv length marker,
- * and additional metadata forllowing that: It follows a pointer
+ * and additional metadata following that: It follows a pointer
  * (union buflib_data*) to the corresponding handle table entry. so that it can
  * be quickly found and updated during compaction. After that follows
  * the pointer to the struct buflib_callbacks associated with this allocation
@@ -62,7 +62,7 @@
  * |L|H|C|cccc|L2|crc|XXXXXX|-L|YYYYYYYYYYYYYYYY|L|H|C|cc|L2|crc|XXXXXXXXXXXXX|AAA|
  *
  * L - length marker (negative if block unallocated)
- * H - handle table enry pointer
+ * H - handle table entry pointer
  * C - pointer to struct buflib_callbacks
  * c - variable sized string identifier
  * L2 - second length marker for string identifier
diff --git a/firmware/include/buflib.h b/firmware/include/buflib.h
index d1ff58720b..50722bb351 100644
--- a/firmware/include/buflib.h
+++ b/firmware/include/buflib.h
@@ -35,12 +35,15 @@
 
 union buflib_data
 {
-    intptr_t val;
-    char name[1]; /* actually a variable sized string */
-    struct buflib_callbacks* ops;
-    char* alloc;
-    union buflib_data *handle;
-    uint32_t crc;
+    intptr_t val;                 /* length of the block in n*sizeof(union buflib_data).
+                                     Includes buflib metadata overhead. A negative value
+                                     indicates block is unallocated */
+    char name[1];                 /* name, actually a variable sized string */
+    struct buflib_callbacks* ops; /* callback functions for move and shrink. Can be NULL */
+    char* alloc;                  /* start of allocated memory area */
+    union buflib_data *handle;    /* pointer to entry in the handle table.
+                                     Used during compaction for fast lookup */
+    uint32_t crc;                 /* checksum of this data to detect corruption */
 };
 
 struct buflib_context