From efdab4d245470808a7573f0cc3620b50bc806231 Mon Sep 17 00:00:00 2001
From: Josef 'Jeff' Sipek <jeff.sipek@dovecot.fi>
Date: Wed, 20 Jun 2018 10:55:53 -0400
Subject: [PATCH] lib: Document the unsafe datastack mempool

---
 src/lib/mempool-unsafe-datastack.c | 42 ++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/src/lib/mempool-unsafe-datastack.c b/src/lib/mempool-unsafe-datastack.c
index d368d55281..7958f380d2 100644
--- a/src/lib/mempool-unsafe-datastack.c
+++ b/src/lib/mempool-unsafe-datastack.c
@@ -3,6 +3,48 @@
 #include "lib.h"
 #include "mempool.h"
 
+/*
+ * The unsafe datastack pool is a very thin wrapper around the datastack
+ * API.  It is a simpler version of the datastack pool that does not do any
+ * sanity checking, it simply forwards the calls to the datastack API.  It
+ * exists to allow some internal APIs to make datastack allocations via the
+ * pool API.
+ *
+ * Note to consumers: Consider using the (safe) datastack pool instead of
+ * this one.
+ *
+ * Implementation
+ * ==============
+ *
+ * Creation
+ * --------
+ *
+ * The unsafe datastack pool is created statically and therefore is
+ * available at any time after the datastack allocator is initialized.
+ *
+ * Allocation & Reallocation
+ * -------------------------
+ *
+ * The p_malloc() and p_realloc() calls get directed to t_malloc0() and
+ * t_try_realloc(), respectively.  There is no additional per-allocation
+ * information to track.
+ *
+ * Freeing
+ * -------
+ *
+ * A no-op.
+ *
+ * Clearing
+ * --------
+ *
+ * A no-op.
+ *
+ * Destruction
+ * -----------
+ *
+ * It is not possible to destroy the unsafe datastack pool.  Any attempt to
+ * unref the pool is a no-op.
+ */
 
 static const char *pool_unsafe_data_stack_get_name(pool_t pool);
 static void pool_unsafe_data_stack_ref(pool_t pool);