Index: trunk/archive/pslib/include/psMemory.h
===================================================================
--- trunk/archive/pslib/include/psMemory.h	(revision 222)
+++ trunk/archive/pslib/include/psMemory.h	(revision 247)
@@ -1,11 +1,14 @@
 #if !defined(PS_MEMORY_H)
 #define PS_MEMORY_H
-#include <stdio.h>
-/**
- * Book-keeping data for storage allocator.
- *
- * N.b. sizeof(psMemBlock) must be chosen such that if ptr is a pointer
- * returned by malloc, then ((char *)ptr + sizeof(psMemBlock)) is properly
- * aligned for all storage types.
+
+/** \file psMemory.h
+ *  \brief Memory alloc/free routines
+ *  \ingroup SystemGroup
+ */
+
+/** Book-keeping data for storage allocator.
+ *  N.b. sizeof(psMemBlock) must be chosen such that if ptr is a pointer
+ *  returned by malloc, then ((char *)ptr + sizeof(psMemBlock)) is properly
+ *  aligned for all storage types.
  */
 typedef struct {
@@ -18,24 +21,16 @@
 } psMemBlock;
 
-/** */
+/** prototype of a basic callback used by memory functions */
 typedef int (*psMemCallback)(const psMemBlock *ptr);
-typedef void (*psMemProblemCallback)(const psMemBlock *ptr,
-				     const char *file, int lineno);
+
+/** prototype of a callback used in error conditions */
+typedef void (*psMemProblemCallback)(const psMemBlock *ptr, const char *file, int lineno);
+
+/** prototype of a callback used when memory runs out */
 typedef void *(*psMemExhaustedCallback)(size_t size);
 
 /*****************************************************************************/
 
-/** Fake for p_psAlloc */
-void *psAlloc(size_t size		//!< Size required
-    );
-/** Fake for p_psRealloc */
-void *psRealloc(void *ptr,		//!< Pointer to re-allocate
-		size_t size		//!< Size required
-    );
-/** Fake for p_psFree */
-void psFree(void *ptr			//!< Pointer to free
-    );
-
-/** Memory allocation */
+/** Memory allocation. Underlying private function called by macro psAlloc. */
 void *p_psAlloc(size_t size,		//!< Size required
 		const char *file,	//!< File of call
@@ -43,5 +38,5 @@
     );
 
-/** Memory re-allocation */
+/** Memory re-allocation.  Underlying private function called by macro psRealloc. */
 void *p_psRealloc(void *ptr,		//!< Pointer to re-allocate
 		  size_t size,		//!< Size required
@@ -50,5 +45,5 @@
     );
 
-/** Free memory */
+/** Free memory.  Underlying private function called by macro psFree. */
 void p_psFree(void *ptr,		//!< Pointer to free
 	      const char *file,		//!< File of call
@@ -56,16 +51,20 @@
     );
 
-/** psAlloc sends file and line number to p_psAlloc */
+/** Memory allocation. psAlloc sends file and line number to p_psAlloc. */
 #define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__)
-/** psRealloc sends file and line number to p_psRealloc */
+
+/** Memory re-allocation.  psRealloc sends file and line number to p_psRealloc. */
 #define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__)
-/** psFree sends file and line number to p_psFree */
+
+/** Free memory.  psFree sends file and line number to p_psFree. */
 #define psFree(size) p_psFree(size, __FILE__, __LINE__)
 
-/*
- * Ensure that any program using malloc/realloc/free will fail to compile
- */
+/** prevent the use of 'malloc'. malloc is re-defined to throw an error in the C preprocessor */
 #define malloc(S) for
+
+/** prevent the use of 'realloc'. realloc is re-defined to throw an error in the C preprocessor */
 #define realloc(P,S) for
+
+/** prevent the use of 'free'. free is re-defined to throw an error in the C preprocessor */
 #define free(P) for
 
@@ -112,3 +111,4 @@
 long psMemSetAllocateID(long id);	//!< set p_psMemAllocateID to id
 long psMemSetFreeID(long id);		//!< set p_psMemFreeID to id
+
 #endif