diff --git a/include/cn-cbor/cn-cbor.h b/include/cn-cbor/cn-cbor.h
index 28a22c6..9ebc5d5 100644
--- a/include/cn-cbor/cn-cbor.h
+++ b/include/cn-cbor/cn-cbor.h
@@ -86,7 +86,8 @@
     /** for use during parsing */
     unsigned long count;
   } v;                          /* TBD: optimize immediate */
-  /** Number of children.  Note: for maps, this is 2x the number of entries */
+  /** Number of children.
+    * @note: for maps, this is 2x the number of entries */
   int length;
   /** The first child value */
   struct cn_cbor* first_child;
@@ -127,6 +128,11 @@
   CN_CBOR_ERR_OUT_OF_MEMORY
 } cn_cbor_error;
 
+/**
+ * Strings matching the `cn_cbor_error` conditions.
+ *
+ * @todo: turn into a function to make the type safety more clear?
+ */
 extern const char *cn_cbor_error_str[];
 
 /**
@@ -141,34 +147,54 @@
 
 #ifdef USE_CBOR_CONTEXT
 
-typedef void* (*cn_alloc_func)(size_t count, size_t size, void *context);
+/**
+ * Allocate and zero out memory.  `count` elements of `size` are required,
+ * as for `calloc(3)`.  The `context` is the `cn_cbor_context` passed in
+ * earlier to the CBOR routine.
+ *
+ * @param[in] count   The number of items to allocate
+ * @param[in] size    The size of each item
+ * @param[in] context The allocation context
+ */
+typedef void* (*cn_calloc_func)(size_t count, size_t size, void *context);
+
+/**
+ * Free memory previously allocated with a context.  If using a pool allocator,
+ * this function will often be a no-op, but it must be supplied in order to
+ * prevent the CBOR library from calling `free(3)`.
+ *
+ * @note: it may be that this is never needed; if so, it will be removed for
+ * clarity and speed.
+ *
+ * @param  context [description]
+ * @return         [description]
+ */
 typedef void (*cn_free_func)(void *ptr, void *context);
 
+/**
+ * The allocation context.
+ */
 typedef struct cn_cbor_context {
-    cn_alloc_func calloc_func;
+    /** The pool `calloc` routine.  Must allocate and zero. */
+    cn_calloc_func calloc_func;
+    /** The pool `free` routine.  Often a no-op, but required. */
     cn_free_func  free_func;
+    /** Typically, the pool object, to be used when calling `calloc_func`
+      * and `free_func` */
     void *context;
 } cn_cbor_context;
 
-#define CN_CALLOC(ctx) ((ctx) && (ctx)->calloc_func) ? \
-    (ctx)->calloc_func(1, sizeof(cn_cbor), (ctx)->context) : \
-    calloc(1, sizeof(cn_cbor));
-#define CN_FREE(ptr, ctx) ((ctx) && (ctx)->free_func) ? \
-    (ctx)->free_func((ptr), (ctx)->context) : \
-    free((ptr));
+/** When USE_CBOR_CONTEXT is defined, many functions take an extra `context`
+  * parameter */
 #define CBOR_CONTEXT , cn_cbor_context *context
+/** When USE_CBOR_CONTEXT is defined, some functions take an extra `context`
+  * parameter at the beginning */
 #define CBOR_CONTEXT_COMMA cn_cbor_context *context,
 
 #else
 
 #define CBOR_CONTEXT
 #define CBOR_CONTEXT_COMMA
-#ifndef CN_CALLOC
-#define CN_CALLOC calloc(1, sizeof(cn_cbor))
-#endif
-#ifndef CN_FREE
-#define CN_FREE free
-#endif
 
 #endif
 
@@ -177,7 +203,7 @@
  *
  * @param[in]  buf          The array of bytes to parse
  * @param[in]  len          The number of bytes in the array
- * @param[in]  context      Allocation context (only if USE_CBOR_CONTEXT is defined)
+ * @param[in]  CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
  * @param[out] errp         Error, if NULL is returned
  * @return                  The parsed CBOR structure, or NULL on error
  */
@@ -214,7 +240,7 @@
  * Free the given CBOR structure.
  *
  * @param[in]  cb           The CBOR value to free
- * @param[in]  context      Allocation context (only if USE_CBOR_CONTEXT is defined)
+ * @param[in]  CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
  */
 void cn_cbor_free(const cn_cbor* cb CBOR_CONTEXT);
 
diff --git a/src/cbor.h b/src/cbor.h
index 547ad65..901f106 100644
--- a/src/cbor.h
+++ b/src/cbor.h
@@ -66,4 +66,47 @@
 #define IB_FLOAT4 (IB_PRIM + AI_4)
 #define IB_FLOAT8 (IB_PRIM + AI_8)
 
+// These definitions are here because they aren't required for the public
+// interface, and they were quite confusing in cn-cbor.h
+
+#ifdef USE_CBOR_CONTEXT
+/**
+ * Allocate enough space for 1 `cn_cbor` structure.
+ *
+ * @param[in]  ctx  The allocation context, or NULL for calloc.
+ * @return          A pointer to a `cn_cbor` or NULL on failure
+ */
+#define CN_CALLOC(ctx) ((ctx) && (ctx)->calloc_func) ? \
+    (ctx)->calloc_func(1, sizeof(cn_cbor), (ctx)->context) : \
+    calloc(1, sizeof(cn_cbor));
+
+/**
+ * Free a
+ * @param  free_func [description]
+ * @return           [description]
+ */
+#define CN_FREE(ptr, ctx) ((ctx) && (ctx)->free_func) ? \
+    (ctx)->free_func((ptr), (ctx)->context) : \
+    free((ptr));
+
+#define CBOR_CONTEXT_PARAM , context
+#define CN_CALLOC_CONTEXT() CN_CALLOC(context)
+#define CN_CBOR_FREE_CONTEXT(p) CN_FREE(p, context)
+
+#else
+
+#define CBOR_CONTEXT_PARAM
+#define CN_CALLOC_CONTEXT() CN_CALLOC
+#define CN_CBOR_FREE_CONTEXT(p) CN_FREE(p)
+
+#ifndef CN_CALLOC
+#define CN_CALLOC calloc(1, sizeof(cn_cbor))
 #endif
+
+#ifndef CN_FREE
+#define CN_FREE free
+#endif
+
+#endif // USE_CBOR_CONTEXT
+
+#endif // CBOR_PROTOCOL_H__
diff --git a/src/cn-cbor.c b/src/cn-cbor.c
index 6249266..a4e30b0 100644
--- a/src/cn-cbor.c
+++ b/src/cn-cbor.c
@@ -19,16 +19,6 @@
 
 #define CN_CBOR_FAIL(code) do { pb->err = code;  goto fail; } while(0)
 
-#ifdef USE_CBOR_CONTEXT
-#define CBOR_CONTEXT_PARAM , context
-#define CN_CALLOC_CONTEXT() CN_CALLOC(context)
-#define CN_CBOR_FREE_CONTEXT(p) CN_FREE(p, context)
-#else
-#define CBOR_CONTEXT_PARAM
-#define CN_CALLOC_CONTEXT() CN_CALLOC
-#define CN_CBOR_FREE_CONTEXT(p) CN_FREE(p)
-#endif
-
 void cn_cbor_free(const cn_cbor* cb CBOR_CONTEXT) {
   cn_cbor* p = (cn_cbor*) cb;
   while (p) {