From: Amos Jeffries <squid3@treenet.co.nz>
Date: Mon, 9 Jan 2017 08:59:21 +0000 (+1300)
Subject: Docs: update some memory API details
X-Git-Tag: M-staged-PR71~313
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a8ef0b3fde8f083923b49a7f06de90064cad7002;p=thirdparty%2Fsquid.git

Docs: update some memory API details

Using text from the ProgrammingGuide/MemPools wiki page (now removed in favour of doxygen)
---

diff --git a/src/mem/Pool.h b/src/mem/Pool.h
index 51c7c8ddc2..71790f72ec 100644
--- a/src/mem/Pool.h
+++ b/src/mem/Pool.h
@@ -321,13 +321,14 @@ struct _MemPoolGlobalStats {
 };
 
 /// \ingroup MemPoolsAPI
+/// Creates a named MemPool of elements with the given size
 #define memPoolCreate MemPools::GetInstance().create
 
 /* Allocator API */
 /**
  \ingroup MemPoolsAPI
  * Initialise iteration through all of the pools.
- \retval  Iterator for use by memPoolIterateNext() and memPoolIterateDone()
+ * \returns Iterator for use by memPoolIterateNext() and memPoolIterateDone()
  */
 extern MemPoolIterator * memPoolIterate(void);
 
@@ -347,10 +348,12 @@ extern void memPoolIterateDone(MemPoolIterator ** iter);
  \ingroup MemPoolsAPI
  \todo Stats API - not sured how to refactor yet
  *
- * Fills MemPoolGlobalStats with statistical data about overall
+ * Fills a MemPoolGlobalStats with statistical data about overall
  * usage for all pools.
  *
- \retval  Number of pools that have at least one object in use.
+ * \param stats   Object to be filled with statistical data.
+ *
+ * \return Number of pools that have at least one object in use.
  *        Ie. number of dirty pools.
  */
 extern int memPoolGetGlobalStats(MemPoolGlobalStats * stats);
diff --git a/src/mem/forward.h b/src/mem/forward.h
index 9d761e7f8a..3bc54466f2 100644
--- a/src/mem/forward.h
+++ b/src/mem/forward.h
@@ -50,14 +50,17 @@ typedef enum {
     MEM_MAX
 } mem_type;
 
+/// Main cleanup handler.
 void memClean(void);
 void memInitModule(void);
 void memCleanModule(void);
 void memConfigure(void);
+/// Allocate one element from the typed pool
 void *memAllocate(mem_type);
 void *memAllocString(size_t net_size, size_t * gross_size);
 void *memAllocBuf(size_t net_size, size_t * gross_size);
 void *memReallocBuf(void *buf, size_t net_size, size_t * gross_size);
+/// Free a element allocated by memAllocate()
 void memFree(void *, int type);
 void memFreeString(size_t size, void *);
 void memFreeBuf(size_t size, void *);