Fix a lot of doxygen warnings. Thanks to Brad Hards for the patch.

I added a few more fixes, and there are still more that might
need a doxygen expert.

PR: 48061
Submitted by: Brad Hards
Reviewed by: poirier


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@830527 13f79535-47bb-0310-9956-ffa450edef68

14 files changed, 55 insertions, 38 deletions

diff --git a/include/ap_mmn.h b/include/ap_mmn.h
index 54067e81df..0156ffc779 100644
--- a/include/ap_mmn.h
+++ b/include/ap_mmn.h
@@ -215,20 +215,22 @@
 /**
  * Determine if the server's current MODULE_MAGIC_NUMBER is at least a
  * specified value.
- * <pre>
+ *
  * Useful for testing for features.
  * For example, suppose you wish to use the apr_table_overlap
  *    function.  You can do this:
  *
+ * \code
  * #if AP_MODULE_MAGIC_AT_LEAST(19980812,2)
  *     ... use apr_table_overlap()
  * #else
  *     ... alternative code which doesn't use apr_table_overlap()
  * #endif
- * </pre>
+ * \endcode
+ *
  * @param major The major module magic number
  * @param minor The minor module magic number
- * @fn AP_MODULE_MAGIC_AT_LEAST(int major, int minor)
+ * @def AP_MODULE_MAGIC_AT_LEAST(int major, int minor)
  */
 #define AP_MODULE_MAGIC_AT_LEAST(major,minor)           \
     ((major) < MODULE_MAGIC_NUMBER_MAJOR                \
diff --git a/include/ap_mpm.h b/include/ap_mpm.h
index 3a0da9de5d..69586ca111 100644
--- a/include/ap_mpm.h
+++ b/include/ap_mpm.h
@@ -95,7 +95,7 @@ AP_DECLARE_HOOK(int, mpm, (apr_pool_t *pconf, apr_pool_t *plog, server_rec *serv
  * @param r The request_rec of the current request
  * @param newproc The resulting process handle.
  * @param progname The program to run 
- * @param const_args the arguments to pass to the new program.  The first 
+ * @param args the arguments to pass to the new program.  The first 
  *                   one should be the program name.
  * @param env The new environment apr_table_t for the new process.  This 
  *            should be a list of NULL-terminated strings.
diff --git a/include/ap_regex.h b/include/ap_regex.h
index 340a27b1d5..2dbfcb35cd 100644
--- a/include/ap_regex.h
+++ b/include/ap_regex.h
@@ -112,7 +112,7 @@ AP_DECLARE(int) ap_regcomp(ap_regex_t *preg, const char *regex, int cflags);
  * @param nmatch Provide information regarding the location of any matches
  * @param pmatch Provide information regarding the location of any matches
  * @param eflags Bitwise OR of any of AP_REG_* flags 
- * @return 0 for successful match, #REG_NOMATCH otherwise
+ * @return 0 for successful match, \p REG_NOMATCH otherwise
  */ 
 AP_DECLARE(int) ap_regexec(const ap_regex_t *preg, const char *string,
                            apr_size_t nmatch, ap_regmatch_t *pmatch, int eflags);
diff --git a/include/ap_regkey.h b/include/ap_regkey.h
index 84e3246a29..5c3b11da7b 100644
--- a/include/ap_regkey.h
+++ b/include/ap_regkey.h
@@ -91,7 +91,7 @@ AP_DECLARE(apr_status_t) ap_regkey_close(ap_regkey_t *key);
 
 /**
  * Win32 Only: Remove the given registry key.
- * @param parentkey The open registry key of the parent, or one of
+ * @param parent The open registry key of the parent, or one of
  * <PRE>
  *           AP_REGKEY_CLASSES_ROOT
  *           AP_REGKEY_CURRENT_CONFIG
@@ -145,6 +145,7 @@ AP_DECLARE(apr_status_t) ap_regkey_value_set(ap_regkey_t *key,
  * Win32 Only: Retrieve a raw byte value from an open key.
  * @param result The raw bytes value retrieved 
  * @param resultsize Pointer to a variable to store the number raw bytes retrieved 
+ * @param resulttype Pointer to a variable to store the registry type of the value retrieved
  * @param key The registry key to retrieve the value from
  * @param valuename The named value to retrieve (pass "" for the default)
  * @param pool The pool used to store the result
diff --git a/include/ap_slotmem.h b/include/ap_slotmem.h
index e43f4af00e..3d4f0620a9 100644
--- a/include/ap_slotmem.h
+++ b/include/ap_slotmem.h
@@ -20,7 +20,7 @@
 /* Memory handler for a shared memory divided in slot.
  */
 /**
- * @file  slotmem.h
+ * @file  ap_slotmem.h
  * @brief Memory Slot Extension Storage Module for Apache
  *
  * @defgroup MEM mem
diff --git a/include/http_config.h b/include/http_config.h
index a140fb7cb8..f72b59c516 100644
--- a/include/http_config.h
+++ b/include/http_config.h
@@ -438,7 +438,7 @@ typedef struct ap_conf_vector_t ap_conf_vector_t;
 /**
  * Generic accessors for other modules to get at their own module-specific
  * data
- * @param conf_vector The vector in which the modules configuration is stored.
+ * @param cv The vector in which the modules configuration is stored.
  *        usually r->per_dir_config or s->module_config
  * @param m The module to get the data for.
  * @return The module-specific data
@@ -449,7 +449,7 @@ AP_DECLARE(void *) ap_get_module_config(const ap_conf_vector_t *cv,
 /**
  * Generic accessors for other modules to set at their own module-specific
  * data
- * @param conf_vector The vector in which the modules configuration is stored.
+ * @param cv The vector in which the modules configuration is stored.
  *        usually r->per_dir_config or s->module_config
  * @param m The module to set the data for.
  * @param val The module-specific data to set
@@ -538,11 +538,11 @@ AP_DECLARE_NONSTD(const char *) ap_set_file_slot(cmd_parms *cmd,
  * @param struct_ptr pointer into a given type
  * @param arg The argument to the directive
  * @return The cmd->help value as the error string
- * @tip This allows simple declarations such as;
- * <pre>
+ * @note This allows simple declarations such as:
+ * @code
  *     AP_INIT_RAW_ARGS("Foo", ap_set_deprecated, NULL, OR_ALL, 
  *         "The Foo directive is no longer supported, use Bar"),
- * </pre>
+ * @endcode
  */
 AP_DECLARE_NONSTD(const char *) ap_set_deprecated(cmd_parms *cmd, 
                                                   void *struct_ptr, 
@@ -575,13 +575,13 @@ AP_DECLARE(const char *) ap_add_module(module *m, apr_pool_t *p);
 AP_DECLARE(void) ap_remove_module(module *m);
 /**
  * Add a module to the chained modules list and the list of loaded modules
- * @param m The module structure of the module to add
+ * @param mod The module structure of the module to add
  * @param p The pool with the same lifetime as the module
  */
 AP_DECLARE(const char *) ap_add_loaded_module(module *mod, apr_pool_t *p);
 /**
  * Remove a module fromthe chained modules list and the list of loaded modules
- * @param m the module structure of the module to remove
+ * @param mod the module structure of the module to remove
  */
 AP_DECLARE(void) ap_remove_loaded_module(module *mod);
 /**
@@ -862,15 +862,17 @@ AP_CORE_DECLARE(ap_conf_vector_t*) ap_create_conn_config(apr_pool_t *p);
 
 /**
  * parse an htaccess file
- * @param resulting htaccess_result
+ * @param result htaccess_result
  * @param r The request currently being served
  * @param override Which overrides are active
+ * @param override_opts Which allow-override-opts bits are set
  * @param path The path to the htaccess file
  * @param access_name The list of possible names for .htaccess files
  * int The status of the current request
  */
 AP_CORE_DECLARE(int) ap_parse_htaccess(ap_conf_vector_t **result, 
-                                       request_rec *r, int override,
+                                       request_rec *r,
+                                       int override,
                                        int override_opts,
                                        const char *path, 
                                        const char *access_name);
@@ -894,7 +896,7 @@ AP_CORE_DECLARE(const char *) ap_init_virtual_host(apr_pool_t *p,
  * @param fname The name of the config file
  * @param conftree The root node of the created config tree
  * @param p Pool for general allocation
- * @param ptem Pool for temporary allocation
+ * @param ptemp Pool for temporary allocation
  */
 AP_DECLARE(const char *) ap_process_resource_config(server_rec *s,
                                                     const char *fname,
@@ -918,7 +920,7 @@ AP_DECLARE(int) ap_process_config_tree(server_rec *s,
 /**
  * Store data which will be retained across unload/load of modules
  * @param key The unique key associated with this module's retained data
- * @param Size in bytes of the retained data (to be allocated)
+ * @param size in bytes of the retained data (to be allocated)
  * @return Address of new retained data structure, initially cleared
  */
 AP_DECLARE(void *) ap_retained_data_create(const char *key, apr_size_t size);
@@ -999,6 +1001,7 @@ AP_DECLARE_HOOK(int,pre_config,(apr_pool_t *pconf,apr_pool_t *plog,
  * @param pconf The config pool
  * @param plog The logging streams pool
  * @param ptemp The temporary pool
+ * @param s the server to operate upon
  * @return OK or DECLINED on success anything else is a error
  */
 AP_DECLARE_HOOK(int,check_config,(apr_pool_t *pconf, apr_pool_t *plog,
diff --git a/include/http_log.h b/include/http_log.h
index d406b811a8..d8d2b02be3 100644
--- a/include/http_log.h
+++ b/include/http_log.h
@@ -272,7 +272,7 @@ typedef struct piped_log piped_log;
  * @param p The pool to allocate out of
  * @param program The program to run in the logging process
  * @return The piped log structure
- * @tip The log program is invoked as APR_PROGRAM_ENV, 
+ * @note The log program is invoked as @p APR_PROGRAM_ENV, 
  *      @see ap_open_piped_log_ex to modify this behavior
  */
 AP_DECLARE(piped_log *) ap_open_piped_log(apr_pool_t *p, const char *program);
diff --git a/include/http_main.h b/include/http_main.h
index dc0a0de61b..d32fae93d6 100644
--- a/include/http_main.h
+++ b/include/http_main.h
@@ -65,7 +65,7 @@ AP_DECLARE_DATA extern apr_array_header_t *ap_server_config_defines;
  * @param status The exit status after sending signal
  * @param pool Memory pool to allocate from
  */
-APR_DECLARE_OPTIONAL_FN(int, ap_signal_server, (int *, apr_pool_t *));
+APR_DECLARE_OPTIONAL_FN(int, ap_signal_server, (int *status, apr_pool_t *pool));
 
 #ifdef __cplusplus
 }
diff --git a/include/http_request.h b/include/http_request.h
index de87d99742..0c9b138d80 100644
--- a/include/http_request.h
+++ b/include/http_request.h
@@ -313,18 +313,18 @@ AP_DECLARE(void) ap_allow_standard_methods(request_rec *r, int reset, ...);
  * the response to the client
  * @param r The current request
  */
-void ap_process_request(request_rec *);
+void ap_process_request(request_rec *r);
 
 /* For post-processing after a handler has finished with a request. (Commonly used after it was suspended) */
 void ap_process_request_after_handler(request_rec *r);
 
-    /**
+/**
  * Process a top-level request from a client, allowing some or all of
  * the response to remain buffered in the core output filter for later,
  * asynchronous write completion
  * @param r The current request
  */
-void ap_process_async_request(request_rec *);
+void ap_process_async_request(request_rec *r);
 
 /**
  * Kill the current request
diff --git a/include/httpd.h b/include/httpd.h
index 3a664a363d..d0ff3b08c9 100644
--- a/include/httpd.h
+++ b/include/httpd.h
@@ -1518,7 +1518,7 @@ AP_DECLARE(char *) ap_os_escape_path(apr_pool_t *p, const char *path, int partia
  * Escape an html string
  * @param p The pool to allocate from
  * @param s The html to escape
- * @param toasc Whether to escape all non-ASCII chars to &#nnn;
+ * @param toasc Whether to escape all non-ASCII chars to \&\#nnn;
  * @return The escaped string
  */
 AP_DECLARE(char *) ap_escape_html2(apr_pool_t *p, const char *s, int toasc);
@@ -1741,9 +1741,9 @@ AP_DECLARE(int) ap_ind(const char *str, char c);	/* Sigh... */
 AP_DECLARE(int) ap_rind(const char *str, char c);
 
 /**
- * Given a string, replace any bare " with \" .
+ * Given a string, replace any bare &quot; with \\&quot; .
  * @param p The pool to allocate memory from
- * @param instring The string to search for "
+ * @param instring The string to search for &quot;
  * @return A copy of the string with escaped quotes 
  */
 AP_DECLARE(char *) ap_escape_quotes(apr_pool_t *p, const char *instring);
diff --git a/include/mod_core.h b/include/mod_core.h
index f7b363de1e..714064c7bb 100644
--- a/include/mod_core.h
+++ b/include/mod_core.h
@@ -75,7 +75,7 @@ AP_DECLARE(void) ap_basic_http_header(request_rec *r, apr_bucket_brigade *bb);
 /**
  * Send an appropriate response to an http TRACE request.
  * @param r The current request
- * @tip returns DONE or the HTTP status error if it handles the TRACE,
+ * @note returns DONE or the HTTP status error if it handles the TRACE,
  * or DECLINED if the request was not for TRACE.
  * request method was not TRACE.
  */
diff --git a/include/mpm_common.h b/include/mpm_common.h
index 8b7077a224..e5fe358853 100644
--- a/include/mpm_common.h
+++ b/include/mpm_common.h
@@ -86,10 +86,11 @@ extern "C" {
  * @param terminate Either 1 or 0.  If 1, send the child processes SIGTERM
  *        each time through the loop.  If 0, give the process time to die
  *        on its own before signalling it.
- * @tip This function requires that a hook is implemented by the MPM: <pre>
+ * @note This function requires that a hook is implemented by the MPM: <pre>
  *  mpm_note_child_killed -- Note the child died in the scoreboard
  * </pre>
- * @tip The MPM child processes which are reclaimed are those listed
+ *
+ * @note The MPM child processes which are reclaimed are those listed
  * in the scoreboard as well as those currently registered via
  * ap_register_extra_mpm_process().
  */
@@ -98,10 +99,12 @@ void ap_reclaim_child_processes(int terminate);
 /**
  * Catch any child processes that have been spawned by the parent process
  * which have exited. This includes processes registered as "other_children".
- * @tip This function requires that a hook is implemented by the MPM: <pre>
+ *
+ * @note This function requires that a hook is implemented by the MPM: <pre>
  *  mpm_note_child_killed -- Note the child died in the scoreboard
  * </pre>
- * @tip The MPM child processes which are relieved are those listed
+ *
+ * @note The MPM child processes which are relieved are those listed
  * in the scoreboard as well as those currently registered via
  * ap_register_extra_mpm_process().
  */
@@ -112,7 +115,8 @@ void ap_relieve_child_processes(void);
  * an MPM child process which has no entry in the scoreboard.
  * @param pid The process id of an MPM child process which should be
  * reclaimed when ap_reclaim_child_processes() is called.
- * @tip If an extra MPM child process terminates prior to calling
+ *
+ * @note If an extra MPM child process terminates prior to calling
  * ap_reclaim_child_processes(), remove it from the list of such processes
  * by calling ap_unregister_extra_mpm_process().
  */
@@ -143,6 +147,8 @@ apr_status_t ap_mpm_safe_kill(pid_t pid, int sig);
  * this process sleeps for the amount of time specified by the MPM defined
  * macro SCOREBOARD_MAINTENANCE_INTERVAL.
  * @param status The return code if a process has died
+ * @param exitcode The returned exit status of the child, if a child process 
+ *                 dies, or the signal that caused the child to die.
  * @param ret The process id of the process that died
  * @param p The pool to allocate out of
  * @param s The server_rec to pass
@@ -154,6 +160,7 @@ void ap_wait_or_timeout(apr_exit_why_e *status, int *exitcode, apr_proc_t *ret,
  * Log why a child died to the error log, if the child died without the
  * parent signalling it.
  * @param pid The child that has died
+ * @param why The return code of the child process
  * @param status The status returned from ap_wait_or_timeout
  * @return 0 on success, APEXIT_CHILDFATAL if MPM should terminate
  */
@@ -204,6 +211,7 @@ struct ap_pod_t {
  * Open the pipe-of-death.  The pipe of death is used to tell all child
  * processes that it is time to die gracefully.
  * @param p The pool to use for allocating the pipe
+ * @param pod the pipe-of-death that is created.
  */
 AP_DECLARE(apr_status_t) ap_mpm_pod_open(apr_pool_t *p, ap_pod_t **pod);
 
@@ -214,20 +222,22 @@ AP_DECLARE(apr_status_t) ap_mpm_pod_check(ap_pod_t *pod);
 
 /**
  * Close the pipe-of-death
+ *
+ * @param pod the pipe-of-death to close.
  */
 AP_DECLARE(apr_status_t) ap_mpm_pod_close(ap_pod_t *pod);
 
 /**
  * Write data to the pipe-of-death, signalling that one child process
  * should die.
- * @param p The pool to use when allocating any required structures.
+ * @param pod the pipe-of-death to write to.
  */
 AP_DECLARE(apr_status_t) ap_mpm_pod_signal(ap_pod_t *pod);
 
 /**
  * Write data to the pipe-of-death, signalling that all child process
  * should die.
- * @param p The pool to use when allocating any required structures.
+ * @param pod The pipe-of-death to write to.
  * @param num The number of child processes to kill
  */
 AP_DECLARE(void) ap_mpm_pod_killpg(ap_pod_t *pod, int num);
diff --git a/include/util_filter.h b/include/util_filter.h
index cbd390f6cf..8c169de6cd 100644
--- a/include/util_filter.h
+++ b/include/util_filter.h
@@ -424,6 +424,7 @@ AP_DECLARE(ap_filter_t *) ap_add_output_filter(const char *name, void *ctx,
  * (as returned by ap_register_output_filter()) rather than a filter name
  *
  * @param f The filter handle to add
+ * @param ctx Context data to set in the filter
  * @param r The request to add this filter for (or NULL if it isn't associated with a request)
  * @param c The connection to add the filter for
  * @note If adding a connection-level output filter (i.e. where the type
diff --git a/include/util_script.h b/include/util_script.h
index d7e7eae080..fe638ee07b 100644
--- a/include/util_script.h
+++ b/include/util_script.h
@@ -113,10 +113,11 @@ AP_DECLARE(int) ap_scan_script_header_err_brigade(request_rec *r,
  *               error, the string that cause the error is stored here. 
  * @param termch Pointer to the last character parsed.
  * @param termarg Pointer to an int to capture the last argument parsed.
- * @param args   String arguments to parse consecutively for headers, 
- *               a NULL argument terminates the list.
+ * 
+ * The varargs are string arguments to parse consecutively for headers, 
+ * with a NULL argument to terminate the list.
+ *
  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
- * @fn int ap_scan_script_header_err_core(request_rec *r, char *buffer, int (*getsfunc)(char *, int, void *), void *getsfunc_data)
  */ 
 AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs(request_rec *r, 
                                                       char *buffer, 
@@ -134,7 +135,6 @@ AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs(request_rec *r,
                    act like gets()
  * @param getsfunc_data The place to read from
  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
- * @fn int ap_scan_script_header_err_core(request_rec *r, char *buffer, int (*getsfunc)(char *, int, void *), void *getsfunc_data)
  */ 
 AP_DECLARE(int) ap_scan_script_header_err_core(request_rec *r, char *buffer,
 				       int (*getsfunc) (char *, int, void *),