pool: document some of the Pool:: fields.

src/util-pool.h

@@ -43,7 +43,8 @@ typedef struct PoolBucket_ {
 typedef struct Pool_ {
     uint32_t max_buckets;
     uint32_t preallocated;
-    uint32_t allocated;
+    uint32_t allocated;         /**< counter of data elements, both currently in
+                                 *   the pool and outside of it (outstanding) */
 
     uint32_t alloc_list_size;
 
@@ -64,8 +65,9 @@ typedef struct Pool_ {
     void (*Free)(void *);
 
     uint32_t elt_size;
-    uint32_t outstanding;
+    uint32_t outstanding;       /**< counter of data items 'in use'. Pretty much
-    uint32_t max_outstanding;
+                                 *   the diff between PoolGet and PoolReturn */
+    uint32_t max_outstanding;   /**< max value of outstanding we saw */
 } Pool;
 
 /* prototypes */