svn commit: r264751 - /apr/apr/branches/1.2.x/include/apr_pools.h

[jo...@apache.org]

Author: jorton
Date: Tue Aug 30 03:07:45 2005
New Revision: 264751

URL: http://svn.apache.org/viewcvs?rev=264751&view=rev
Log:
Merge r264750 from trunk:

* include/apr_pools.h: Clarify docs on cleanups.

Submitted by: Jonathan Wakely <zilla kayari.org>

Modified:
    apr/apr/branches/1.2.x/include/apr_pools.h

Modified: apr/apr/branches/1.2.x/include/apr_pools.h
URL: http://svn.apache.org/viewcvs/apr/apr/branches/1.2.x/include/apr_pools.h?rev=264751&r1=264750&r2=264751&view=diff
==============================================================================
--- apr/apr/branches/1.2.x/include/apr_pools.h (original)
+++ apr/apr/branches/1.2.x/include/apr_pools.h Tue Aug 30 03:07:45 2005
@@ -476,8 +476,8 @@
                                                 apr_pool_t *pool);
 
 
-/*
- * Cleanup
+/**
+ * @defgroup PoolCleanup  Pool Cleanup Functions
  *
  * Cleanups are performed in the reverse order they were registered.  That is:
  * Last In, First Out.  A cleanup function can safely allocate memory from
@@ -486,6 +486,8 @@
  * terminates.  Cleanups have to take caution in calling functions that
  * create subpools. Subpools, created during cleanup will NOT automatically
  * be cleaned up.  In other words, cleanups are to clean up after themselves.
+ *
+ * @{
  */
 
 /**
@@ -504,9 +506,13 @@
     apr_status_t (*child_cleanup)(void *));
 
 /**
- * Remove a previously registered cleanup function
- * @param p The pool remove the cleanup from
- * @param data The data to remove from cleanup
+ * Remove a previously registered cleanup function.
+ * 
+ * The cleanup most recently registered with @a p having the same values of
+ * @a data and @a cleanup will be removed.
+ *
+ * @param p The pool to remove the cleanup from
+ * @param data The data of the registered cleanup
  * @param cleanup The function to remove from cleanup
  * @remarks For some strange reason only the plain_cleanup is handled by this
  *          function
@@ -515,7 +521,12 @@
                                         apr_status_t (*cleanup)(void *));
 
 /**
- * Replace the child cleanup of a previously registered cleanup
+ * Replace the child cleanup function of a previously registered cleanup.
+ * 
+ * The cleanup most recently registered with @a p having the same values of
+ * @a data and @a plain_cleanup will have the registered child cleanup
+ * function replaced with @a child_cleanup.
+ *
  * @param p The pool of the registered cleanup
  * @param data The data of the registered cleanup
  * @param plain_cleanup The plain cleanup function of the registered cleanup
@@ -528,9 +539,13 @@
     apr_status_t (*child_cleanup)(void *));
 
 /**
- * Run the specified cleanup function immediately and unregister it. Use
- * @a data instead of the data that was registered with the cleanup.
- * @param p The pool remove the cleanup from
+ * Run the specified cleanup function immediately and unregister it.
+ *
+ * The cleanup most recently registered with @a p having the same values of
+ * @a data and @a cleanup will be removed and @a cleanup will be called
+ * with @a data as the argument.
+ *
+ * @param p The pool to remove the cleanup from
  * @param data The data to remove from cleanup
  * @param cleanup The function to remove from cleanup
  */
@@ -540,20 +555,23 @@
     apr_status_t (*cleanup)(void *));
 
 /**
- * An empty cleanup function
- * @param data The data to cleanup
+ * An empty cleanup function.
+ * 
+ * Passed to apr_pool_cleanup_register() when no cleanup is required.
+ *
+ * @param data The data to cleanup, will not be used by this function.
  */
 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
 
-/* Preparing for exec() --- close files, etc., but *don't* flush I/O
- * buffers, *don't* wait for subprocesses, and *don't* free any memory.
- */
 /**
- * Run all of the child_cleanups, so that any unnecessary files are
- * closed because we are about to exec a new program
+ * Run all registered child cleanups, in preparation for an exec()
+ * call in a forked child -- close files, etc., but *don't* flush I/O
+ * buffers, *don't* wait for subprocesses, and *don't* free any
+ * memory.
  */
 APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
 
+/** @} */
 
 /**
  * @defgroup PoolDebug Pool Debugging functions.