Hi,
As requested by Joe Orton, I've prepared a new patch to clarify the
doxygen comments for the pool cleanup functions.
The new patch is attached to the bug report and to this mail.
Any comments are welcome,
jon
--
"Once, during Prohibition, I was forced to live for days on nothing but
food and water."
- W.C. Fields
Index: include/apr_pools.h
===================================================================
--- include/apr_pools.h (revision 231517)
+++ include/apr_pools.h (working copy)
@@ -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,8 +555,11 @@
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);
@@ -549,11 +567,15 @@
* 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.
+ *
+ * Run all of the child_cleanups registered with the global pool and
+ * all sub-pools, so that any unnecessary files are closed before we
+ * exec a new program.
*/
APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
+/** @} */
/**
* @defgroup PoolDebug Pool Debugging functions.
