Fix doc errors in APR header files.

PR: 55133
Submitted by: Mike Rumph <mike.rumph oracle.com>


git-svn-id: http://svn.apache.org/repos/asf/apr/apr/trunk@1496407 13f79535-47bb-0310-9956-ffa450edef68

14 files changed, 56 insertions, 49 deletions

diff --git a/include/apr_allocator.h b/include/apr_allocator.h
index 5d6677645..70d31efa0 100644
--- a/include/apr_allocator.h
+++ b/include/apr_allocator.h
@@ -131,7 +131,7 @@ APR_DECLARE(apr_pool_t *) apr_allocator_owner_get(apr_allocator_t *allocator)
 /**
  * Set the current threshold at which the allocator should start
  * giving blocks back to the system.
- * @param allocator The allocator the set the threshold on
+ * @param allocator The allocator to set the threshold on
  * @param size The threshold.  0 == unlimited.
  */
 APR_DECLARE(void) apr_allocator_max_free_set(apr_allocator_t *allocator,
diff --git a/include/apr_dbd.h b/include/apr_dbd.h
index 0fe0688ba..1e8da00ab 100644
--- a/include/apr_dbd.h
+++ b/include/apr_dbd.h
@@ -107,10 +107,10 @@ APR_DECLARE(apr_status_t) apr_dbd_get_driver(apr_pool_t *pool, const char *name,
 
 /** apr_dbd_open_ex: open a connection to a backend
  *
+ *  @param driver - driver struct.
  *  @param pool - working pool
  *  @param params - arguments to driver (implementation-dependent)
  *  @param handle - pointer to handle to return
- *  @param driver - driver struct.
  *  @param error - descriptive error.
  *  @return APR_SUCCESS for success
  *  @return APR_EGENERAL if driver exists but connection failed
@@ -147,10 +147,10 @@ APR_DECLARE(apr_status_t) apr_dbd_open_ex(const apr_dbd_driver_t *driver,
 
 /** apr_dbd_open: open a connection to a backend
  *
+ *  @param driver - driver struct.
  *  @param pool - working pool
  *  @param params - arguments to driver (implementation-dependent)
  *  @param handle - pointer to handle to return
- *  @param driver - driver struct.
  *  @return APR_SUCCESS for success
  *  @return APR_EGENERAL if driver exists but connection failed
  *  @see apr_dbd_open_ex
@@ -161,8 +161,8 @@ APR_DECLARE(apr_status_t) apr_dbd_open(const apr_dbd_driver_t *driver,
 
 /** apr_dbd_close: close a connection to a backend
  *
- *  @param handle - handle to close
  *  @param driver - driver struct.
+ *  @param handle - handle to close
  *  @return APR_SUCCESS for success or error status
  */
 APR_DECLARE(apr_status_t) apr_dbd_close(const apr_dbd_driver_t *driver,
diff --git a/include/apr_errno.h b/include/apr_errno.h
index 57ad99269..4ee292e38 100644
--- a/include/apr_errno.h
+++ b/include/apr_errno.h
@@ -45,7 +45,7 @@ typedef int apr_status_t;
 
 /**
  * Return a human readable string describing the specified error.
- * @param statcode The error code the get a string for.
+ * @param statcode The error code to get a string for.
  * @param buf A buffer to hold the error string.
  * @param bufsize Size of the buffer to hold the string.
  */
@@ -126,7 +126,7 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf,
  * use within apr-util. This space is reserved above that used by APR
  * internally.
  * @note This number MUST be smaller than APR_OS_ERRSPACE_SIZE by a
- *       large enough amount that APR has sufficient room for it's
+ *       large enough amount that APR has sufficient room for its
  *       codes.
  */
 #define APR_UTIL_ERRSPACE_SIZE 20000
@@ -135,7 +135,7 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf,
  */
 #define APR_OS_START_STATUS    (APR_OS_START_ERROR + APR_OS_ERRSPACE_SIZE)
 /**
- * APR_UTIL_START_STATUS is where APR-Util starts defining it's
+ * APR_UTIL_START_STATUS is where APR-Util starts defining its
  * status codes.
  */
 #define APR_UTIL_START_STATUS   (APR_OS_START_STATUS + \
diff --git a/include/apr_escape.h b/include/apr_escape.h
index bc77c3c9d..73dc6cce0 100644
--- a/include/apr_escape.h
+++ b/include/apr_escape.h
@@ -130,7 +130,7 @@ APR_DECLARE(apr_status_t) apr_escape_path_segment(char *escaped,
  * Escape a path segment, as defined in RFC1808, returning the result from a
  * pool.
  * @param p Pool to allocate from
- * @param url String to be escaped
+ * @param str String to be escaped
  * @return A string allocated from the pool on success, the original string
  * if no characters are encoded or the string is NULL.
  */
@@ -149,7 +149,7 @@ APR_DECLARE(const char *) apr_pescape_path_segment(apr_pool_t *p,
  * something with a '/' in it (and thus does not prefix "./").
  * @param escaped Optional buffer to write the encoded string, can be
  * NULL
- * @param str The original string
+ * @param path The original string
  * @param slen The length of the original string, or APR_ESCAPE_STRING
  * @param partial If non zero, suppresses the prepending of "./"
  * @param len If present, returns the length of the string
@@ -199,7 +199,7 @@ APR_DECLARE(apr_status_t) apr_escape_urlencoded(char *escaped, const char *str,
  * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1, returning
  * the result from a pool.
  * @param p Pool to allocate from
- * @param url String to be escaped
+ * @param str String to be escaped
  * @return A string allocated from the pool on success, the original string
  * if no characters are encoded or if the string was NULL.
  */
@@ -319,7 +319,7 @@ APR_DECLARE(const char *) apr_pescape_echo(apr_pool_t *p, const char *str,
  * Convert binary data to a hex encoding.
  * @param dest The destination buffer, can be NULL
  * @param src The original buffer
- * @param slen The length of the original buffer
+ * @param srclen The length of the original buffer
  * @param colon If not zero, insert colon characters between hex digits.
  * @param len If present, returns the length of the string
  * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL
@@ -332,7 +332,7 @@ APR_DECLARE(apr_status_t) apr_escape_hex(char *dest, const void *src,
  * pool.
  * @param p Pool to allocate from
  * @param src The original buffer
- * @param srclen The length of the original buffer
+ * @param slen The length of the original buffer
  * @param colon If not zero, insert colon characters between hex digits.
  * @return A zero padded buffer allocated from the pool on success, or
  * NULL if src was NULL.
diff --git a/include/apr_file_info.h b/include/apr_file_info.h
index 94e84e876..b3006ac4c 100644
--- a/include/apr_file_info.h
+++ b/include/apr_file_info.h
@@ -316,7 +316,7 @@ APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir);
  * @param filepath the pathname to parse for its root component
  * @param flags the desired rules to apply, from
  * <PRE>
- *      APR_FILEPATH_NATIVE    Use native path seperators (e.g. '\' on Win32)
+ *      APR_FILEPATH_NATIVE    Use native path separators (e.g. '\' on Win32)
  *      APR_FILEPATH_TRUENAME  Tests that the root exists, and makes it proper
  * </PRE>
  * @param p the pool to allocate the new path string from
@@ -328,7 +328,7 @@ APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir);
  * test for the validity of that root (e.g., that a drive d:/ or network 
  * share //machine/foovol/). 
  * The function returns APR_ERELATIVE if filepath isn't rooted (an
- * error), APR_EINCOMPLETE if the root path is ambigious (but potentially
+ * error), APR_EINCOMPLETE if the root path is ambiguous (but potentially
  * legitimate, e.g. "/" on Windows is incomplete because it doesn't specify
  * the drive letter), or APR_EBADPATH if the root is simply invalid.
  * APR_SUCCESS is returned if filepath is an absolute path.
@@ -362,7 +362,7 @@ APR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath,
  * @param pathelts the returned components of the search path
  * @param liststr the search path (e.g., <tt>getenv("PATH")</tt>)
  * @param p the pool to allocate the array and path components from
- * @remark empty path componenta do not become part of @a pathelts.
+ * @remark empty path components do not become part of @a pathelts.
  * @remark the path separator in @a liststr is system specific;
  * e.g., ':' on Unix, ';' on Windows, etc.
  */
diff --git a/include/apr_hooks.h b/include/apr_hooks.h
index 8330b8aa8..896ea72f3 100644
--- a/include/apr_hooks.h
+++ b/include/apr_hooks.h
@@ -313,24 +313,24 @@ APR_DECLARE_DATA extern apr_pool_t *apr_hook_global_pool;
 
 /**
  * A global variable to determine if debugging information about the
- * hooks functions should be printed
+ * hooks functions should be printed.
  */ 
 APR_DECLARE_DATA extern int apr_hook_debug_enabled;
 
 /**
- * The name of the module that is currently registering a function
+ * The name of the module that is currently registering a function.
  */ 
 APR_DECLARE_DATA extern const char *apr_hook_debug_current;
 
 /**
- * Register a hook function to be sorted
+ * Register a hook function to be sorted.
  * @param szHookName The name of the Hook the function is registered for
  * @param aHooks The array which stores all of the functions for this hook
  */
 APR_DECLARE(void) apr_hook_sort_register(const char *szHookName, 
                                         apr_array_header_t **aHooks);
 /**
- * Sort all of the registerd functions for a given hook
+ * Sort all of the registered functions for a given hook.
  */
 APR_DECLARE(void) apr_hook_sort_all(void);
 
diff --git a/include/apr_inherit.h b/include/apr_inherit.h
index b7f7480f1..b9fe56fe4 100644
--- a/include/apr_inherit.h
+++ b/include/apr_inherit.h
@@ -28,7 +28,7 @@
  * Prototype for type-specific declarations of apr_foo_inherit_set 
  * functions.  
  * @remark Doxygen unwraps this macro (via doxygen.conf) to provide 
- * actual help for each specific occurance of apr_foo_inherit_set.
+ * actual help for each specific occurrence of apr_foo_inherit_set.
  * @remark the linkage is specified for APR. It would be possible to expand
  *       the macros to support other linkages.
  */
@@ -40,7 +40,7 @@
  * Prototype for type-specific declarations of apr_foo_inherit_unset 
  * functions.  
  * @remark Doxygen unwraps this macro (via doxygen.conf) to provide 
- * actual help for each specific occurance of apr_foo_inherit_unset.
+ * actual help for each specific occurrence of apr_foo_inherit_unset.
  * @remark the linkage is specified for APR. It would be possible to expand
  *       the macros to support other linkages.
  */
diff --git a/include/apr_mmap.h b/include/apr_mmap.h
index 77d697f5b..c14de1928 100644
--- a/include/apr_mmap.h
+++ b/include/apr_mmap.h
@@ -120,7 +120,7 @@ struct apr_mmap_t {
 /** 
  * Create a new mmap'ed file out of an existing APR file.
  * @param newmmap The newly created mmap'ed file.
- * @param file The file turn into an mmap.
+ * @param file The file to turn into an mmap.
  * @param offset The offset into the file to start the data pointer at.
  * @param size The size of the file
  * @param flag bit-wise or of:
diff --git a/include/apr_optional_hooks.h b/include/apr_optional_hooks.h
index 1e3801a8e..ac100a248 100644
--- a/include/apr_optional_hooks.h
+++ b/include/apr_optional_hooks.h
@@ -33,11 +33,11 @@ extern "C" {
  * @{
  */
 /**
- * Function to implemnt the APR_OPTIONAL_HOOK Macro
+ * Function to implement the APR_OPTIONAL_HOOK Macro
  * @internal
  * @see APR_OPTIONAL_HOOK
  *
- * @param name The name of the hook
+ * @param szName The name of the hook
  * @param pfn A pointer to a function that will be called
  * @param aszPre a NULL-terminated array of strings that name modules whose hooks should precede this one
  * @param aszSucc a NULL-terminated array of strings that name modules whose hooks should succeed this one
diff --git a/include/apr_pools.h b/include/apr_pools.h
index 6f50ade8f..0b17561bb 100644
--- a/include/apr_pools.h
+++ b/include/apr_pools.h
@@ -71,10 +71,10 @@ typedef struct apr_pool_t apr_pool_t;
  * <pre>
  *    APR_POOL_DECLARE_ACCESSOR(file);
  * becomes:
- *    APR_DECLARE(apr_pool_t *) apr_file_pool_get(apr_file_t *ob);
+ *    APR_DECLARE(apr_pool_t *) apr_file_pool_get(const apr_file_t *thefile);
  * </pre>
  * @remark Doxygen unwraps this macro (via doxygen.conf) to provide 
- * actual help for each specific occurance of apr_foo_pool_get.
+ * actual help for each specific occurrence of apr_foo_pool_get.
  * @remark the linkage is specified for APR. It would be possible to expand
  *       the macros to support other linkages.
  */
@@ -118,15 +118,15 @@ typedef struct apr_pool_t apr_pool_t;
  *
  * |   |   |   |   | x |   |   |   |  Pool owner checking.  On each use of a
  *                                    pool, check if the current thread is the
- *                                    pools owner.  If not, abort().  In
+ *                                    pool's owner.  If not, abort().  In
  *                                    combination with the verbose flag above,
  *                                    it will output OWNER in such an event
  *                                    prior to aborting.  Use the debug
  *                                    function apr_pool_owner_set() to switch
- *                                    a pools ownership.
+ *                                    a pool's ownership.
  *
  * When no debug level was specified, assume general debug mode.
- * If level 0 was specified, debugging is switched off
+ * If level 0 was specified, debugging is switched off.
  * </pre>
  */
 #if defined(APR_POOL_DEBUG)
@@ -204,7 +204,7 @@ APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
  * @param newpool The pool we have just created.
  * @param abort_fn A function to use if the pool cannot allocate more memory.
  * @param allocator The allocator to use with the new pool.  If NULL a
- *        new allocator will be crated with newpool as owner.
+ *        new allocator will be created with the new pool as owner.
  * @remark An unmanaged pool is a special pool without a parent; it will
  *         NOT be destroyed upon apr_terminate.  It must be explicitly
  *         destroyed by calling apr_pool_destroy, to prevent memory leaks.
@@ -213,7 +213,7 @@ APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
  * @warning Any child cleanups registered against the new pool, or
  *         against sub-pools thereof, will not be executed during an
  *         invocation of apr_proc_create(), so resources created in an
- *         "unmanaged" pool heirarchy will leak to child processes.
+ *         "unmanaged" pool hierarchy will leak to child processes.
  */
 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool,
                                                    apr_abortfunc_t abort_fn,
@@ -229,7 +229,7 @@ APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool,
  * @param file_line Where the function is called from.
  *        This is usually APR_POOL__FILE_LINE__.
  * @remark Only available when APR_POOL_DEBUG is defined.
- *         Call this directly if you have you apr_pool_create_ex
+ *         Call this directly if you have your apr_pool_create_ex
  *         calls in a wrapper function and wish to override
  *         the file_line argument to reflect the caller of
  *         your wrapper function.  If you do not have
@@ -257,7 +257,7 @@ APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
  * @param file_line Where the function is called from.
  *        This is usually APR_POOL__FILE_LINE__.
  * @remark Only available when APR_POOL_DEBUG is defined.
- *         Call this directly if you have you apr_pool_create_unmanaged_ex
+ *         Call this directly if you have your apr_pool_create_unmanaged_ex
  *         calls in a wrapper function and wish to override
  *         the file_line argument to reflect the caller of
  *         your wrapper function.  If you do not have
@@ -304,7 +304,7 @@ APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
 #endif
 
 /**
- * Create a new pool.
+ * Create a new unmanaged pool.
  * @param newpool The pool we have just created.
  */
 #if defined(DOXYGEN)
@@ -343,7 +343,7 @@ APR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1)));
  * @param file_line Where the function is called from.
  *        This is usually APR_POOL__FILE_LINE__.
  * @remark Only available when APR_POOL_DEBUG is defined.
- *         Call this directly if you have you apr_pool_clear
+ *         Call this directly if you have your apr_pool_clear
  *         calls in a wrapper function and wish to override
  *         the file_line argument to reflect the caller of
  *         your wrapper function.  If you do not have
@@ -373,7 +373,7 @@ APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1)));
  * @param file_line Where the function is called from.
  *        This is usually APR_POOL__FILE_LINE__.
  * @remark Only available when APR_POOL_DEBUG is defined.
- *         Call this directly if you have you apr_pool_destroy
+ *         Call this directly if you have your apr_pool_destroy
  *         calls in a wrapper function and wish to override
  *         the file_line argument to reflect the caller of
  *         your wrapper function.  If you do not have
@@ -591,7 +591,7 @@ APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
 
 /**
  * Register a function to be called when a pool is cleared or destroyed
- * @param p The pool register the cleanup with
+ * @param p The pool to register the cleanup with
  * @param data The data to pass to the cleanup function.
  * @param plain_cleanup The function to call when the pool is cleared
  *                      or destroyed
@@ -607,11 +607,11 @@ APR_DECLARE(void) apr_pool_cleanup_register(
 /**
  * Register a function to be called when a pool is cleared or destroyed.
  *
- * Unlike apr_pool_cleanup_register which register a cleanup
- * that is called AFTER all subpools are destroyed this function register
- * a function that will be called before any of the subpool is destoryed.
+ * Unlike apr_pool_cleanup_register which registers a cleanup
+ * that is called AFTER all subpools are destroyed, this function registers
+ * a function that will be called before any of the subpools are destroyed.
  *
- * @param p The pool register the cleanup with
+ * @param p The pool to register the cleanup with
  * @param data The data to pass to the cleanup function.
  * @param plain_cleanup The function to call when the pool is cleared
  *                      or destroyed
diff --git a/include/apr_queue.h b/include/apr_queue.h
index 93bf2e41f..1d09e9de3 100644
--- a/include/apr_queue.h
+++ b/include/apr_queue.h
@@ -22,7 +22,7 @@
  * @brief Thread Safe FIFO bounded queue
  * @note Since most implementations of the queue are backed by a condition
  * variable implementation, it isn't available on systems without threads.
- * Although condition variables are some times available without threads.
+ * Although condition variables are sometimes available without threads.
  */
 
 #include "apu.h"
diff --git a/include/apr_reslist.h b/include/apr_reslist.h
index ee94f07e9..4e09e12aa 100644
--- a/include/apr_reslist.h
+++ b/include/apr_reslist.h
@@ -44,7 +44,7 @@ typedef struct apr_reslist_t apr_reslist_t;
 /* Generic constructor called by resource list when it needs to create a
  * resource.
  * @param resource opaque resource
- * @param param flags
+ * @param params flags
  * @param pool  Pool
  */
 typedef apr_status_t (*apr_reslist_constructor)(void **resource, void *params,
@@ -53,7 +53,7 @@ typedef apr_status_t (*apr_reslist_constructor)(void **resource, void *params,
 /* Generic destructor called by resource list when it needs to destroy a
  * resource.
  * @param resource opaque resource
- * @param param flags
+ * @param params flags
  * @param pool  Pool
  */
 typedef apr_status_t (*apr_reslist_destructor)(void *resource, void *params,
@@ -111,12 +111,17 @@ APR_DECLARE(apr_status_t) apr_reslist_destroy(apr_reslist_t *reslist);
  * Retrieve a resource from the list, creating a new one if necessary.
  * If we have met our maximum number of resources, we will block
  * until one becomes available.
+ * @param reslist The resource list.
+ * @param resource An address where the pointer to the resource
+ *                will be stored.
  */
 APR_DECLARE(apr_status_t) apr_reslist_acquire(apr_reslist_t *reslist,
                                               void **resource);
 
 /**
  * Return a resource back to the list of available resources.
+ * @param reslist The resource list.
+ * @param resource The resource to return to the list.
  */
 APR_DECLARE(apr_status_t) apr_reslist_release(apr_reslist_t *reslist,
                                               void *resource);
@@ -140,6 +145,8 @@ APR_DECLARE(apr_uint32_t) apr_reslist_acquired_count(apr_reslist_t *reslist);
  * Invalidate a resource in the pool - e.g. a database connection
  * that returns a "lost connection" error and can't be restored.
  * Use this instead of apr_reslist_release if the resource is bad.
+ * @param reslist The resource list.
+ * @param resource The resource to invalidate.
  */
 APR_DECLARE(apr_status_t) apr_reslist_invalidate(apr_reslist_t *reslist,
                                                  void *resource);
diff --git a/include/apr_thread_proc.h b/include/apr_thread_proc.h
index 1ecbfaa60..7fcd4b6ec 100644
--- a/include/apr_thread_proc.h
+++ b/include/apr_thread_proc.h
@@ -115,7 +115,7 @@ typedef enum {
 #define APR_OC_REASON_DEATH         0     /**< child has died, caller must call
                                            * unregister still */
 #define APR_OC_REASON_UNWRITABLE    1     /**< currently unused. */
-#define APR_OC_REASON_RESTART       2     /**< a restart is occuring, perform
+#define APR_OC_REASON_RESTART       2     /**< a restart is occurring, perform
                                            * any necessary cleanup (including
                                            * sending a special signal to child)
                                            */
@@ -124,7 +124,7 @@ typedef enum {
                                            * kill the child) */
 #define APR_OC_REASON_LOST          4     /**< somehow the child exited without
                                            * us knowing ... buggy os? */
-#define APR_OC_REASON_RUNNING       5     /**< a health check is occuring, 
+#define APR_OC_REASON_RUNNING       5     /**< a health check is occurring, 
                                            * for most maintainence functions
                                            * this is a no-op.
                                            */
diff --git a/include/apr_user.h b/include/apr_user.h
index 0179e2264..0e0a3ac5a 100644
--- a/include/apr_user.h
+++ b/include/apr_user.h
@@ -81,7 +81,7 @@ APR_DECLARE(apr_status_t) apr_uid_name_get(char **username, apr_uid_t userid,
  * Get the userid (and groupid) for the specified username
  * @param userid   Returns the user id
  * @param groupid  Returns the user's group id
- * @param username The username to lookup
+ * @param username The username to look up
  * @param p The pool from which to allocate working space
  * @remark This function is available only if APR_HAS_USER is defined.
  */
@@ -103,7 +103,7 @@ APR_DECLARE(apr_status_t) apr_uid_homepath_get(char **dirname,
  * Compare two user identifiers for equality.
  * @param left One uid to test
  * @param right Another uid to test
- * @return APR_SUCCESS if the apr_uid_t strutures identify the same user,
+ * @return APR_SUCCESS if the apr_uid_t structures identify the same user,
  * APR_EMISMATCH if not, APR_BADARG if an apr_uid_t is invalid.
  * @remark This function is available only if APR_HAS_USER is defined.
  */
@@ -137,7 +137,7 @@ APR_DECLARE(apr_status_t) apr_gid_get(apr_gid_t *groupid,
  * Compare two group identifiers for equality.
  * @param left One gid to test
  * @param right Another gid to test
- * @return APR_SUCCESS if the apr_gid_t strutures identify the same group,
+ * @return APR_SUCCESS if the apr_gid_t structures identify the same group,
  * APR_EMISMATCH if not, APR_BADARG if an apr_gid_t is invalid.
  * @remark This function is available only if APR_HAS_USER is defined.
  */