From 1e87b04dc88079ddf969598caf43336174cfa893 Mon Sep 17 00:00:00 2001 From: Christophe Jaillet Date: Sat, 19 Jul 2014 17:22:30 +0000 Subject: [PATCH] Fix doxygen comments. In trunk: r1611210 , r1611252, r1611481, r1611919 git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1611925 13f79535-47bb-0310-9956-ffa450edef68 --- include/http_connection.h | 6 +- include/util_varbuf.h | 132 ++++++++++++++++++++------------------ include/util_xml.h | 7 +- 3 files changed, 75 insertions(+), 70 deletions(-) diff --git a/include/http_connection.h b/include/http_connection.h index f73670b442..11f8dd1b60 100644 --- a/include/http_connection.h +++ b/include/http_connection.h @@ -32,10 +32,6 @@ #ifdef __cplusplus extern "C" { #endif -/** - * @file http_connection.h - * @brief Apache connection library - */ /** * This is the protocol module driver. This calls all of the @@ -145,5 +141,5 @@ AP_DECLARE(apr_bucket *) ap_bucket_eoc_create(apr_bucket_alloc_t *list); } #endif -#endif /* !APACHE_HTTP_REQUEST_H */ +#endif /* !APACHE_HTTP_CONNECTION_H */ /** @} */ diff --git a/include/util_varbuf.h b/include/util_varbuf.h index 3285939264..8e45578e04 100644 --- a/include/util_varbuf.h +++ b/include/util_varbuf.h @@ -18,12 +18,13 @@ * @file util_varbuf.h * @brief Apache resizable variable length buffer library * + * @defgroup APACHE_CORE_VARBUF Variable length buffer library + * @ingroup APACHE_CORE + * * This set of functions provides resizable buffers. While the primary * usage is with NUL-terminated strings, most functions also work with * arbitrary binary data. - * - * @defgroup APACHE_CORE_VARBUF Variable length buffer library - * @ingroup APACHE_CORE + * * @{ */ @@ -42,87 +43,93 @@ extern "C" { #define AP_VARBUF_UNKNOWN APR_SIZE_MAX struct ap_varbuf_info; -/** A resizable buffer */ +/** A resizable buffer. */ struct ap_varbuf { - /** the actual buffer; will point to a const '\0' if avail == 0 and - * to memory of the same lifetime as the pool otherwise */ + /** The actual buffer; will point to a const '\\0' if avail == 0 and + * to memory of the same lifetime as the pool otherwise. */ char *buf; - /** allocated size of the buffer (minus one for the final \0); - * must only be changed using ap_varbuf_grow() */ + /** Allocated size of the buffer (minus one for the final \\0); + * must only be changed using ap_varbuf_grow(). */ apr_size_t avail; - /** length of string in buffer, or AP_VARBUF_UNKNOWN. This determines how + /** Length of string in buffer, or AP_VARBUF_UNKNOWN. This determines how * much memory is copied by ap_varbuf_grow() and where * ap_varbuf_strmemcat() will append to the buffer. */ apr_size_t strlen; - /** the pool for memory allocations and for registering the cleanup; - * the buffer memory will be released when this pool is cleared */ + /** The pool for memory allocations and for registering the cleanup; + * the buffer memory will be released when this pool is cleared. */ apr_pool_t *pool; - /** opaque info for memory allocation */ + /** Opaque info for memory allocation. */ struct ap_varbuf_info *info; }; -/** initialize a resizable buffer. It is safe to re-initialize a prevously - * used ap_varbuf. The old buffer will be released when the corresponding - * pool is cleared. The buffer remains usable until the pool is cleared, - * even if the ap_varbuf was located on the stack and has gone out of scope. - * @param pool the pool to allocate small buffers from and to register the - * cleanup with - * @param vb pointer to the ap_varbuf struct - * @param init_size the initial size of the buffer (see ap_varbuf_grow() for details) +/** + * Initialize a resizable buffer. It is safe to re-initialize a previously + * used ap_varbuf. The old buffer will be released when the corresponding + * pool is cleared. The buffer remains usable until the pool is cleared, + * even if the ap_varbuf was located on the stack and has gone out of scope. + * @param pool The pool to allocate small buffers from and to register + * the cleanup with + * @param vb Pointer to the ap_varbuf struct + * @param init_size The initial size of the buffer (see ap_varbuf_grow() for + * details) */ AP_DECLARE(void) ap_varbuf_init(apr_pool_t *pool, struct ap_varbuf *vb, apr_size_t init_size); -/** grow a resizable buffer. If the vb->buf cannot be grown in place, it will - * be reallocated and the first vb->strlen + 1 bytes of memory will be copied - * to the new location. If vb->strlen == AP_VARBUF_UNKNOWN, the whole buffer - * is copied. - * @param vb pointer to the ap_varbuf struct - * @param new_size the minimum new size of the buffer +/** + * Grow a resizable buffer. If the vb->buf cannot be grown in place, it will + * be reallocated and the first vb->strlen + 1 bytes of memory will be copied + * to the new location. If vb->strlen == AP_VARBUF_UNKNOWN, the whole buffer + * is copied. + * @param vb Pointer to the ap_varbuf struct + * @param new_size The minimum new size of the buffer * @note ap_varbuf_grow() will usually at least double vb->buf's size with - * every invocation in order to reduce reallications. + * every invocation in order to reduce reallocations. * @note ap_varbuf_grow() will use pool memory for small and allocator * mem nodes for larger allocations. * @note ap_varbuf_grow() will call vb->pool's abort function if out of memory. */ AP_DECLARE(void) ap_varbuf_grow(struct ap_varbuf *vb, apr_size_t new_size); -/** Release memory from a ap_varbuf immediately, if possible. - * This allows to free large buffers before the corresponding pool is - * cleared. Only larger allocations using mem nodes will be freed. - * @param vb pointer to the ap_varbuf struct +/** + * Release memory from a ap_varbuf immediately, if possible. + * This allows to free large buffers before the corresponding pool is + * cleared. Only larger allocations using mem nodes will be freed. + * @param vb Pointer to the ap_varbuf struct * @note After ap_varbuf_free(), vb must not be used unless ap_varbuf_init() * is called again. */ AP_DECLARE(void) ap_varbuf_free(struct ap_varbuf *vb); -/** Concatenate a string to an ap_varbuf. vb->strlen determines where +/** + * Concatenate a string to an ap_varbuf. vb->strlen determines where * the string is appended in the buffer. If vb->strlen == AP_VARBUF_UNKNOWN, * the string will be appended at the first NUL byte in the buffer. * If len == 0, ap_varbuf_strmemcat() does nothing. - * @param vb pointer to the ap_varbuf struct - * @param str the string to append; must be at least len bytes long - * @param len the number of characters of *str to concatenate to the buf + * @param vb Pointer to the ap_varbuf struct + * @param str The string to append; must be at least len bytes long + * @param len The number of characters of *str to concatenate to the buf * @note vb->strlen will be set to the length of the new string * @note if len != 0, vb->buf will always be NUL-terminated */ AP_DECLARE(void) ap_varbuf_strmemcat(struct ap_varbuf *vb, const char *str, int len); -/** Duplicate an ap_varbuf's content into pool memory - * @param p the pool to allocate from - * @param vb the ap_varbuf to copy from - * @param prepend an optional buffer to prepend (may be NULL) - * @param prepend_len length of prepend - * @param append an optional buffer to append (may be NULL) - * @param append_len length of append - * @param new_len where to store the length of the resulting string - * (may be NULL) - * @return the new string +/** + * Duplicate an ap_varbuf's content into pool memory. + * @param p The pool to allocate from + * @param vb The ap_varbuf to copy from + * @param prepend An optional buffer to prepend (may be NULL) + * @param prepend_len Length of prepend + * @param append An optional buffer to append (may be NULL) + * @param append_len Length of append + * @param new_len Where to store the length of the resulting string + * (may be NULL) + * @return The new string * @note ap_varbuf_pdup() uses vb->strlen to determine how much memory to * copy. It works even if 0-bytes are embedded in vb->buf, prepend, or * append. @@ -135,23 +142,25 @@ AP_DECLARE(char *) ap_varbuf_pdup(apr_pool_t *p, struct ap_varbuf *vb, apr_size_t *new_len); -/** Concatenate a string to an ap_varbuf - * @param vb pointer to the ap_varbuf struct - * @param str the string to append +/** + * Concatenate a string to an ap_varbuf. + * @param vb Pointer to the ap_varbuf struct + * @param str The string to append * @note vb->strlen will be set to the length of the new string */ #define ap_varbuf_strcat(vb, str) ap_varbuf_strmemcat(vb, str, strlen(str)) -/** Perform string substitutions based on regexp match, using an ap_varbuf. +/** + * Perform string substitutions based on regexp match, using an ap_varbuf. * This function behaves like ap_pregsub(), but appends to an ap_varbuf * instead of allocating the result from a pool. - * @param vb The ap_varbuf to which the string will be appended - * @param input An arbitrary string containing $1 through $9. These are - * replaced with the corresponding matched sub-expressions - * @param source The string that was originally matched to the regex - * @param nmatch the nmatch returned from ap_pregex - * @param pmatch the pmatch array returned from ap_pregex - * @param maxlen the maximum string length to append to vb, 0 for unlimited + * @param vb The ap_varbuf to which the string will be appended + * @param input An arbitrary string containing $1 through $9. These are + * replaced with the corresponding matched sub-expressions + * @param source The string that was originally matched to the regex + * @param nmatch The nmatch returned from ap_pregex + * @param pmatch The pmatch array returned from ap_pregex + * @param maxlen The maximum string length to append to vb, 0 for unlimited * @return APR_SUCCESS if successful * @note Just like ap_pregsub(), this function does not copy the part of * *source before the matching part (i.e. the first pmatch[0].rm_so @@ -166,11 +175,12 @@ AP_DECLARE(apr_status_t) ap_varbuf_regsub(struct ap_varbuf *vb, ap_regmatch_t pmatch[], apr_size_t maxlen); -/** Read a line from an ap_configfile_t and append it to an ap_varbuf. - * @param vb pointer to the ap_varbuf struct - * @param cfp pointer to the ap_configfile_t - * @param max_len maximum line length, including leading/trailing whitespace - * @return see ap_cfg_getline() +/** + * Read a line from an ap_configfile_t and append it to an ap_varbuf. + * @param vb Pointer to the ap_varbuf struct + * @param cfp Pointer to the ap_configfile_t + * @param max_len Maximum line length, including leading/trailing whitespace + * @return See ap_cfg_getline() * @note vb->strlen will be set to the length of the line * @note If vb->strlen equals AP_VARBUF_UNKNOWN, it will be set to * strlen(vb->buf) first. diff --git a/include/util_xml.h b/include/util_xml.h index e60d348bbb..9faaed15c6 100644 --- a/include/util_xml.h +++ b/include/util_xml.h @@ -35,11 +35,10 @@ extern "C" { #endif /** - * Get XML post data and parse it - * @param r The current request - * @param pdoc The XML post data + * Get XML post data and parse it. + * @param r The current request + * @param pdoc The XML post data * @return HTTP status code - * @fn int ap_xml_parse_input(request_rec *r, apr_xml_doc **pdoc) */ AP_DECLARE(int) ap_xml_parse_input(request_rec *r, apr_xml_doc **pdoc); -- 2.40.0