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 51c7c8ddc2041701369e9fdd986d84eb86efc673..71790f72ecda579881725bd1177fc695f3c6a5aa 100644 (file)
--- 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 9d761e7f8a683b5abe0cd3afb4c0502a0807c373..3bc54466f2ecd26b577401f639a4563d2c67c947 100644 (file)
--- 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 *);