From 2e16676c15d100c343e4650d5671d4eca0dba797 Mon Sep 17 00:00:00 2001
From: Michael Poole <mdpoole@troilus.org>
Date: Tue, 5 Oct 2004 01:54:30 +0000
Subject: [PATCH] Doxyfy ircd_alloc.h and ircd_alloc.c.

git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@1220 c9e4aea6-c8fd-4c43-8297-357d70d61c8c
---
 include/ircd_alloc.h | 15 ++++++++++-----
 ircd/ircd_alloc.c    | 37 ++++++++++++++++++++++++++++++-------
 2 files changed, 40 insertions(+), 12 deletions(-)

diff --git a/include/ircd_alloc.h b/include/ircd_alloc.h
index 385e7e5..a2aa32f 100644
--- a/include/ircd_alloc.h
+++ b/include/ircd_alloc.h
@@ -1,7 +1,6 @@
 /*
  * IRC - Internet Relay Chat, include/ircd_alloc.h
  * Copyright (C) 1999 Thomas Helvey <tomh@inxpress.net>
- *                   
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -18,8 +17,10 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  *
  * Commentary by Bleep (Thomas Helvey)
- *
- * $Id$
+ */
+/** @file
+ * @brief IRC daemon memory allocation functions.
+ * @version $Id$
  */
 #ifndef INCLUDED_ircd_alloc_h
 #define INCLUDED_ircd_alloc_h
@@ -27,20 +28,25 @@
 /*
  * memory resource allocation and test functions
  */
+/** Type of handler for out-of-memory conditions. */
 typedef void (*OutOfMemoryHandler)(void);
 extern void set_nomem_handler(OutOfMemoryHandler handler);
 
 /* The mappings for the My* functions... */
+/** Helper macro for standard allocations. */
 #define MyMalloc(size) \
   DoMalloc(size, "malloc", __FILE__, __LINE__)
 
+/** Helper macro for zero-initialized allocations. */
 #define MyCalloc(nelem, size) \
   DoMallocZero(size * nelem, "calloc", __FILE__, __LINE__)
 
+/** Helper macro for freeing memory. */
 #define MyFree(p) \
   if (p) \
     DoFree(p, __FILE__, __LINE__)
 
+/** Helper macro for reallocating memory. */
 #define MyRealloc(p, size) \
   DoRealloc(p, size, __FILE__, __LINE__)
 
@@ -51,8 +57,7 @@ extern void set_nomem_handler(OutOfMemoryHandler handler);
 #define INCLUDED_stdlib_h
 #endif
 
-extern OutOfMemoryHandler noMemHandler;
-
+/** Implementation macro for freeing memory. */
 #define DoFree(x, file, line) do { free((x)); (x) = 0; } while(0)
 extern void* DoMalloc(size_t len, const char*, const char*, int);
 extern void* DoMallocZero(size_t len, const char*, const char*, int);
diff --git a/ircd/ircd_alloc.c b/ircd/ircd_alloc.c
index 51df9fe..62944c5 100644
--- a/ircd/ircd_alloc.c
+++ b/ircd/ircd_alloc.c
@@ -1,9 +1,9 @@
 /************************************************************************
  *   IRC - Internet Relay Chat, ircd/ircd_alloc.c
  *   Copyright (C) 1999 Thomas Helvey (BleepSoft)
- *                     
+ *
  *   See file AUTHORS in IRC package for additional names of
- *   the programmers. 
+ *   the programmers.
  *
  *   This program is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU General Public License as published by
@@ -18,8 +18,10 @@
  *   You should have received a copy of the GNU General Public License
  *   along with this program; if not, write to the Free Software
  *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- *   $Id$
+ */
+/** @file
+ * @brief IRC daemon memory allocation functions.
+ * @version $Id$
  */
 #include "config.h"
 
@@ -32,10 +34,10 @@
 
 static void nomem_handler(void);
 
-/* Those ugly globals... */
-OutOfMemoryHandler noMemHandler = nomem_handler;
-void *malloc_tmp;
+/** Variable holding out-of-memory callback. */
+static OutOfMemoryHandler noMemHandler = nomem_handler;
 
+/** Default handler for out-of-memory conditions. */
 static void
 nomem_handler(void)
 {
@@ -47,12 +49,20 @@ nomem_handler(void)
 #endif
 }
 
+/** Set callback function for out-of-memory conditions. */
 void
 set_nomem_handler(OutOfMemoryHandler handler)
 {
   noMemHandler = handler;
 }
 
+/** Allocate memory.
+ * @param[in] size Number of bytes to allocate.
+ * @param[in] x Type of allocation (ignored).
+ * @param[in] y Name of file doing allocation (ignored).
+ * @param[in] z Line number doing allocation (ignored).
+ * @return Newly allocated block of memory.
+ */
 void* DoMalloc(size_t size, const char* x, const char* y, int z)
 {
   void* t = malloc(size);
@@ -61,6 +71,13 @@ void* DoMalloc(size_t size, const char* x, const char* y, int z)
   return t;
 }
 
+/** Allocate zero-initialized memory.
+ * @param[in] size Number of bytes to allocate.
+ * @param[in] x Type of allocation (ignored).
+ * @param[in] y Name of file doing allocation (ignored).
+ * @param[in] z Line number doing allocation (ignored).
+ * @return Newly allocated block of memory.
+ */
 void* DoMallocZero(size_t size, const char* x, const char* y, int z)
 {
   void* t = malloc(size);
@@ -70,6 +87,12 @@ void* DoMallocZero(size_t size, const char* x, const char* y, int z)
   return t;
 }
 
+/** Resize an allocated block of memory.
+ * @param[in] orig Original block to resize.
+ * @param[in] size Minimum size for new block.
+ * @param[in] file Name of file doing reallocation (ignored).
+ * @param[in] line Line number doing reallocation (ignored).
+ */
 void* DoRealloc(void *orig, size_t size, const char *file, int line)
 {
   void* t = realloc(orig, size);
-- 
2.20.1