From 7d0b693c1792b88fcfed9b523890c1073f794def Mon Sep 17 00:00:00 2001
From: Josef 'Jeff' Sipek <jeff.sipek@dovecot.fi>
Date: Tue, 19 Jun 2018 16:08:40 -0400
Subject: [PATCH] lib: Document the system mempool

---
 src/lib/mempool-system.c | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/src/lib/mempool-system.c b/src/lib/mempool-system.c
index 7686ac4eb9..507b70a73d 100644
--- a/src/lib/mempool-system.c
+++ b/src/lib/mempool-system.c
@@ -6,6 +6,39 @@
 #include "safe-memset.h"
 #include "mempool.h"
 
+/*
+ * The system pool is a thin wrapper around calloc() and free().  It exists
+ * to allow direct heap usage via the pool API.
+ *
+ * Implementation
+ * ==============
+ *
+ * Creation
+ * --------
+ *
+ * The system pool is created statically and therefore is available at any
+ * time.
+ *
+ * Allocation, Reallocation & Freeing
+ * ----------------------------------
+ *
+ * The p_malloc(), p_realloc(), and p_free() calls get directed to calloc(),
+ * realloc(), and free().  There is no additional per-allocation information
+ * to track.
+ *
+ * Clearing
+ * --------
+ *
+ * Not supported.  Attempting to clear the system pool will result in a
+ * panic.
+ *
+ * Destruction
+ * -----------
+ *
+ * It is not possible to destroy the system pool.  Any attempt to unref the
+ * pool is a no-op.
+ */
+
 #ifndef HAVE_MALLOC_USABLE_SIZE
 /* no extra includes needed */
 #elif defined (HAVE_MALLOC_NP_H)
-- 
2.47.3