From: Jeff Trawick Date: Wed, 22 Jan 2014 19:15:14 +0000 (+0000) Subject: doxygen improvements X-Git-Tag: 2.5.0-alpha~4625 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=350815887354fbba2cb12cadb0e1171dc444b631;p=apache doxygen improvements git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1560482 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/include/ap_mpm.h b/include/ap_mpm.h index 9fca65dc71..ba7a95b0f5 100644 --- a/include/ap_mpm.h +++ b/include/ap_mpm.h @@ -88,6 +88,7 @@ extern "C" { * @param plog the log pool, reset after the config file is read * @param server_conf the global server config. * @return DONE for shutdown OK otherwise. + * @ingroup hooks */ AP_DECLARE_HOOK(int, mpm, (apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf)) @@ -113,42 +114,75 @@ AP_DECLARE(apr_status_t) ap_os_create_privileged_process( apr_procattr_t *attr, apr_pool_t *p); -/* Subtypes/Values for AP_MPMQ_IS_THREADED and AP_MPMQ_IS_FORKED */ -#define AP_MPMQ_NOT_SUPPORTED 0 /* This value specifies that an */ - /* MPM is not capable of */ - /* threading or forking. */ -#define AP_MPMQ_STATIC 1 /* This value specifies that */ - /* an MPM is using a static */ - /* number of threads or daemons */ -#define AP_MPMQ_DYNAMIC 2 /* This value specifies that */ - /* an MPM is using a dynamic */ - /* number of threads or daemons */ +/** @defgroup mpmq MPM query + * @{ + */ + +/** @defgroup thrdfrk Subtypes/Values returned for AP_MPMQ_IS_THREADED and AP_MPMQ_IS_FORKED + * @ingroup mpmq + * @{ + */ +#define AP_MPMQ_NOT_SUPPORTED 0 /**< This value specifies that an + * MPM is not capable of + * threading or forking. */ +#define AP_MPMQ_STATIC 1 /**< This value specifies that + * an MPM is using a static + * number of threads or daemons */ +#define AP_MPMQ_DYNAMIC 2 /**< This value specifies that + * an MPM is using a dynamic + * number of threads or daemons */ +/** @} */ -/* Values returned for AP_MPMQ_MPM_STATE */ +/** @defgroup qstate Values returned for AP_MPMQ_MPM_STATE + * @ingroup mpmq + * @{ + */ #define AP_MPMQ_STARTING 0 #define AP_MPMQ_RUNNING 1 #define AP_MPMQ_STOPPING 2 +/** @} */ -#define AP_MPMQ_MAX_DAEMON_USED 1 /* Max # of daemons used so far */ -#define AP_MPMQ_IS_THREADED 2 /* MPM can do threading */ -#define AP_MPMQ_IS_FORKED 3 /* MPM can do forking */ -#define AP_MPMQ_HARD_LIMIT_DAEMONS 4 /* The compiled max # daemons */ -#define AP_MPMQ_HARD_LIMIT_THREADS 5 /* The compiled max # threads */ -#define AP_MPMQ_MAX_THREADS 6 /* # of threads/child by config */ -#define AP_MPMQ_MIN_SPARE_DAEMONS 7 /* Min # of spare daemons */ -#define AP_MPMQ_MIN_SPARE_THREADS 8 /* Min # of spare threads */ -#define AP_MPMQ_MAX_SPARE_DAEMONS 9 /* Max # of spare daemons */ -#define AP_MPMQ_MAX_SPARE_THREADS 10 /* Max # of spare threads */ -#define AP_MPMQ_MAX_REQUESTS_DAEMON 11 /* Max # of requests per daemon */ -#define AP_MPMQ_MAX_DAEMONS 12 /* Max # of daemons by config */ -#define AP_MPMQ_MPM_STATE 13 /* starting, running, stopping */ -#define AP_MPMQ_IS_ASYNC 14 /* MPM can process async connections */ -#define AP_MPMQ_GENERATION 15 /* MPM generation */ -#define AP_MPMQ_HAS_SERF 16 /* MPM can drive serf internally */ +/** @defgroup qcodes Query codes for ap_mpm_query() + * @ingroup mpmq + * @{ + */ +/** Max # of daemons used so far */ +#define AP_MPMQ_MAX_DAEMON_USED 1 +/** MPM can do threading */ +#define AP_MPMQ_IS_THREADED 2 +/** MPM can do forking */ +#define AP_MPMQ_IS_FORKED 3 +/** The compiled max # daemons */ +#define AP_MPMQ_HARD_LIMIT_DAEMONS 4 +/** The compiled max # threads */ +#define AP_MPMQ_HARD_LIMIT_THREADS 5 +/** \# of threads/child by config */ +#define AP_MPMQ_MAX_THREADS 6 +/** Min # of spare daemons */ +#define AP_MPMQ_MIN_SPARE_DAEMONS 7 +/** Min # of spare threads */ +#define AP_MPMQ_MIN_SPARE_THREADS 8 +/** Max # of spare daemons */ +#define AP_MPMQ_MAX_SPARE_DAEMONS 9 +/** Max # of spare threads */ +#define AP_MPMQ_MAX_SPARE_THREADS 10 +/** Max # of requests per daemon */ +#define AP_MPMQ_MAX_REQUESTS_DAEMON 11 +/** Max # of daemons by config */ +#define AP_MPMQ_MAX_DAEMONS 12 +/** starting, running, stopping */ +#define AP_MPMQ_MPM_STATE 13 +/** MPM can process async connections */ +#define AP_MPMQ_IS_ASYNC 14 +/** MPM generation */ +#define AP_MPMQ_GENERATION 15 +/** MPM can drive serf internally */ +#define AP_MPMQ_HAS_SERF 16 +/** @} */ /** * Query a property of the current MPM. - * @param query_code One of APM_MPMQ_* + * @param query_code One of AP_MPMQ_* * @param result A location to place the result of the query * @return APR_EGENERAL if an mpm-query hook has not been registered; * APR_SUCCESS or APR_ENOTIMPL otherwise @@ -159,6 +193,7 @@ AP_DECLARE(apr_status_t) ap_os_create_privileged_process( */ AP_DECLARE(apr_status_t) ap_mpm_query(int query_code, int *result); +/** @} */ typedef void (ap_mpm_callback_fn_t)(void *baton); @@ -214,6 +249,7 @@ typedef enum mpm_child_status { * scoreboard slot. * @param state One of the mpm_child_status values. Modules should ignore * unrecognized values. + * @ingroup hooks */ AP_DECLARE_HOOK(void,child_status,(server_rec *s, pid_t pid, ap_generation_t gen, int slot, mpm_child_status state)) @@ -224,6 +260,7 @@ AP_DECLARE_HOOK(void,child_status,(server_rec *s, pid_t pid, ap_generation_t gen * * @param s The main server_rec. * @param gen The server generation which is now completely finished. + * @ingroup hooks */ AP_DECLARE_HOOK(void,end_generation,(server_rec *s, ap_generation_t gen)) @@ -247,6 +284,14 @@ typedef struct ap_exception_info_t { pid_t pid; } ap_exception_info_t; +/** + * Run the fatal_exception hook for each module; this hook is run + * from some MPMs in the event of a child process crash, if the + * server was built with --enable-exception-hook and the + * EnableExceptionHook directive is On. + * @param ei information about the exception + * @ingroup hooks + */ AP_DECLARE_HOOK(int,fatal_exception,(ap_exception_info_t *ei)) #endif /*AP_ENABLE_EXCEPTION_HOOK*/ diff --git a/include/ap_regex.h b/include/ap_regex.h index be41226bee..7fed5ff077 100644 --- a/include/ap_regex.h +++ b/include/ap_regex.h @@ -155,6 +155,8 @@ AP_DECLARE(apr_size_t) ap_regerror(int errcode, const ap_regex_t *preg, * Return an array of named regex backreferences * @param preg The precompiled regex * @param names The array to which the names will be added + * @param prefix An optional prefix to add to the returned names. AP_REG_MATCH + * is the recommended prefix. * @param upper If non zero, uppercase the names */ AP_DECLARE(int) ap_regname(const ap_regex_t *preg, diff --git a/include/http_config.h b/include/http_config.h index da24d70f79..da3b4a2dac 100644 --- a/include/http_config.h +++ b/include/http_config.h @@ -1229,6 +1229,7 @@ AP_CORE_DECLARE(void *) ap_set_config_vectors(server_rec *server, * Run the header parser functions for each module * @param r The current request * @return OK or DECLINED + * @ingroup hooks */ AP_DECLARE_HOOK(int,header_parser,(request_rec *r)) @@ -1238,6 +1239,7 @@ AP_DECLARE_HOOK(int,header_parser,(request_rec *r)) * @param plog The logging streams pool * @param ptemp The temporary pool * @return OK or DECLINED on success anything else is a error + * @ingroup hooks */ AP_DECLARE_HOOK(int,pre_config,(apr_pool_t *pconf,apr_pool_t *plog, apr_pool_t *ptemp)) @@ -1249,6 +1251,7 @@ AP_DECLARE_HOOK(int,pre_config,(apr_pool_t *pconf,apr_pool_t *plog, * @param ptemp The temporary pool * @param s the server to operate upon * @return OK or DECLINED on success anything else is a error + * @ingroup hooks */ AP_DECLARE_HOOK(int,check_config,(apr_pool_t *pconf, apr_pool_t *plog, apr_pool_t *ptemp, server_rec *s)) @@ -1261,7 +1264,7 @@ AP_DECLARE_HOOK(int,check_config,(apr_pool_t *pconf, apr_pool_t *plog, * @note To avoid reordering problems due to different buffering, hook * functions should only apr_file_*() to print to stdout/stderr and * not simple printf()/fprintf(). - * + * @ingroup hooks */ AP_DECLARE_HOOK(void,test_config,(apr_pool_t *pconf, server_rec *s)) @@ -1272,6 +1275,7 @@ AP_DECLARE_HOOK(void,test_config,(apr_pool_t *pconf, server_rec *s)) * @param ptemp The temporary pool * @param s The list of server_recs * @return OK or DECLINED on success anything else is a error + * @ingroup hooks */ AP_DECLARE_HOOK(int,post_config,(apr_pool_t *pconf,apr_pool_t *plog, apr_pool_t *ptemp,server_rec *s)) @@ -1283,6 +1287,7 @@ AP_DECLARE_HOOK(int,post_config,(apr_pool_t *pconf,apr_pool_t *plog, * @param ptemp The temporary pool * @param s The list of server_recs * @return OK or DECLINED on success anything else is a error + * @ingroup hooks */ AP_DECLARE_HOOK(int,open_logs,(apr_pool_t *pconf,apr_pool_t *plog, apr_pool_t *ptemp,server_rec *s)) @@ -1291,6 +1296,7 @@ AP_DECLARE_HOOK(int,open_logs,(apr_pool_t *pconf,apr_pool_t *plog, * Run the child_init functions for each module * @param pchild The child pool * @param s The list of server_recs in this server + * @ingroup hooks */ AP_DECLARE_HOOK(void,child_init,(apr_pool_t *pchild, server_rec *s)) @@ -1298,6 +1304,7 @@ AP_DECLARE_HOOK(void,child_init,(apr_pool_t *pchild, server_rec *s)) * Run the handler functions for each module * @param r The request_rec * @remark non-wildcard handlers should HOOK_MIDDLE, wildcard HOOK_LAST + * @ingroup hooks */ AP_DECLARE_HOOK(int,handler,(request_rec *r)) @@ -1311,6 +1318,7 @@ AP_DECLARE_HOOK(int,handler,(request_rec *r)) * @param lookup_uri Controls whether the caller actually wants content or not. * lookup is set when the quick_handler is called out of * ap_sub_req_lookup_uri() + * @ingroup hooks */ AP_DECLARE_HOOK(int,quick_handler,(request_rec *r, int lookup_uri)) @@ -1318,6 +1326,7 @@ AP_DECLARE_HOOK(int,quick_handler,(request_rec *r, int lookup_uri)) * Retrieve the optional functions for each module. * This is run immediately before the server starts. Optional functions should * be registered during the hook registration phase. + * @ingroup hooks */ AP_DECLARE_HOOK(void,optional_fn_retrieve,(void)) @@ -1334,6 +1343,7 @@ AP_DECLARE_HOOK(void,optional_fn_retrieve,(void)) * APR_ENOENT or APR_ENOTDIR if no htaccess file exists, * AP_DECLINED to let later modules do the opening, * any other error code on error. + * @ingroup hooks */ AP_DECLARE_HOOK(apr_status_t,open_htaccess, (request_rec *r, const char *dir_name, const char *access_name, diff --git a/include/httpd.h b/include/httpd.h index 0439e97e27..0333c01d5f 100644 --- a/include/httpd.h +++ b/include/httpd.h @@ -2336,7 +2336,7 @@ AP_DECLARE(apr_status_t) ap_password_validate(request_rec *r, /** * Short function to execute a command and return the first line of - * output minus \r \n. Useful for "obscuring" passwords via exec calls + * output minus \\r \\n. Useful for "obscuring" passwords via exec calls * @param p the pool to allocate from * @param cmd the command to execute * @param argv the arguments to pass to the cmd