From 872b922c47e8f616abe514262f9bd0a43f52c4c8 Mon Sep 17 00:00:00 2001 From: Christophe Jaillet Date: Sun, 26 Aug 2018 10:05:37 +0000 Subject: Slightly improve doxygen generated documentation. Add some links to function Backport of r1839182 from trunk resp. r1839183 from 1.7.x git-svn-id: https://svn.apache.org/repos/asf/apr/apr/branches/1.6.x@1839184 13f79535-47bb-0310-9956-ffa450edef68 --- include/apr_atomic.h | 2 +- include/apr_file_info.h | 4 ++-- include/apr_general.h | 25 +++++++++++++------------ include/apr_portable.h | 2 +- include/apr_strings.h | 4 ++-- include/apr_tables.h | 8 ++++---- 6 files changed, 23 insertions(+), 22 deletions(-) diff --git a/include/apr_atomic.h b/include/apr_atomic.h index 60e4bb54d..7ea257123 100644 --- a/include/apr_atomic.h +++ b/include/apr_atomic.h @@ -41,7 +41,7 @@ extern "C" { * @param p pool * @return APR_SUCCESS on successful completion * @remark Programs do NOT need to call this directly. APR will call this - * automatically from apr_initialize. + * automatically from apr_initialize(). * @internal */ APR_DECLARE(apr_status_t) apr_atomic_init(apr_pool_t *p); diff --git a/include/apr_file_info.h b/include/apr_file_info.h index 1d19eb6a3..cfddc68da 100644 --- a/include/apr_file_info.h +++ b/include/apr_file_info.h @@ -50,7 +50,7 @@ extern "C" { /** apr_filetype_e values for the filetype member of the * apr_file_info_t structure - * @warning: Not all of the filetypes below can be determined. + * @warning Not all of the filetypes below can be determined. * For example, a given platform might not correctly report * a socket descriptor as APR_SOCK if that type isn't * well-identified on that platform. In such cases where @@ -413,7 +413,7 @@ APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p); * Determine the encoding used internally by the FilePath functions * @param style points to a variable which receives the encoding style flag * @param p the pool to allocate any working storage - * @remark Use @c apr_os_locale_encoding and/or @c apr_os_default_encoding + * @remark Use apr_os_locale_encoding() and/or apr_os_default_encoding() * to get the name of the path encoding if it's not UTF-8. */ APR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p); diff --git a/include/apr_general.h b/include/apr_general.h index c7389ec92..fa073c859 100644 --- a/include/apr_general.h +++ b/include/apr_general.h @@ -170,8 +170,8 @@ void *memchr(const void *s, int c, size_t n); /** * Setup any APR internal data structures. This MUST be the first function * called for any APR library. It is safe to call apr_initialize several - * times as long as apr_terminate is called the same number of times. - * @remark See apr_app_initialize if this is an application, rather than + * times as long as apr_terminate() is called the same number of times. + * @remark See apr_app_initialize() if this is an application, rather than * a library consumer of apr. */ APR_DECLARE(apr_status_t) apr_initialize(void); @@ -184,9 +184,9 @@ APR_DECLARE(apr_status_t) apr_initialize(void); * @param argc Pointer to the argc that may be corrected * @param argv Pointer to the argv that may be corrected * @param env Pointer to the env that may be corrected, may be NULL - * @remark See apr_initialize if this is a library consumer of apr. - * Otherwise, this call is identical to apr_initialize, and must be closed - * with a call to apr_terminate at the end of program execution. + * @remark See apr_initialize() if this is a library consumer of apr. + * Otherwise, this call is identical to apr_initialize(), and must be closed + * with a call to apr_terminate() at the end of program execution. */ APR_DECLARE(apr_status_t) apr_app_initialize(int *argc, char const * const * *argv, @@ -198,20 +198,21 @@ APR_DECLARE(apr_status_t) apr_app_initialize(int *argc, * apr_initialize() or apr_app_initialize(). * @remark An APR program must call this function at termination once it * has stopped using APR services. The APR developers suggest using - * atexit to ensure this is called. When using APR from a language - * other than C that has problems with the calling convention, use - * apr_terminate2() instead. + * @c atexit(apr_terminate) to ensure this is called. When using APR + * from a language other than C that has problems with the calling + * convention, use apr_terminate2() instead. + * @see apr_terminate2 */ APR_DECLARE_NONSTD(void) apr_terminate(void); /** * Tear down any APR internal data structures which aren't torn down - * automatically, same as apr_terminate - * @remark An APR program must call either the apr_terminate or apr_terminate2 + * automatically, same as apr_terminate() + * @remark An APR program must call either the apr_terminate() or apr_terminate2 * function once it it has finished using APR services. The APR - * developers suggest using atexit(apr_terminate) to ensure this is done. + * developers suggest using @c atexit(apr_terminate) to ensure this is done. * apr_terminate2 exists to allow non-c language apps to tear down apr, - * while apr_terminate is recommended from c language applications. + * while apr_terminate() is recommended from c language applications. */ APR_DECLARE(void) apr_terminate2(void); diff --git a/include/apr_portable.h b/include/apr_portable.h index 9a8d3bd33..f56997e4d 100644 --- a/include/apr_portable.h +++ b/include/apr_portable.h @@ -535,7 +535,7 @@ APR_DECLARE(const char*) apr_os_default_encoding(apr_pool_t *pool); /** * Get the name of the current locale character set. * @param pool the pool to allocate the name from, if needed - * @remark Defers to apr_os_default_encoding if the current locale's + * @remark Defers to apr_os_default_encoding() if the current locale's * data can't be retrieved on this system. */ APR_DECLARE(const char*) apr_os_locale_encoding(apr_pool_t *pool); diff --git a/include/apr_strings.h b/include/apr_strings.h index c0642adb2..d5f8719d2 100644 --- a/include/apr_strings.h +++ b/include/apr_strings.h @@ -101,10 +101,10 @@ APR_DECLARE(char *) apr_pstrdup(apr_pool_t *p, const char *s); * @param s The block of characters to duplicate * @param n The number of characters to duplicate * @return The new string or NULL if s == NULL - * @remark This is a faster alternative to apr_pstrndup, for use + * @remark This is a faster alternative to apr_pstrndup(), for use * when you know that the string being duplicated really * has 'n' or more characters. If the string might contain - * fewer characters, use apr_pstrndup. + * fewer characters, use apr_pstrndup(). */ APR_DECLARE(char *) apr_pstrmemdup(apr_pool_t *p, const char *s, apr_size_t n) #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) diff --git a/include/apr_tables.h b/include/apr_tables.h index fe3084bd6..27974c0e8 100644 --- a/include/apr_tables.h +++ b/include/apr_tables.h @@ -179,7 +179,7 @@ APR_DECLARE(void) apr_array_cat(apr_array_header_t *dst, * @param p The pool to allocate the copy of the array out of * @param arr The array to copy * @return An exact copy of the array passed in - * @remark The alternate apr_array_copy_hdr copies only the header, and arranges + * @remark The alternate apr_array_copy_hdr() copies only the header, and arranges * for the elements to be copied if (and only if) the code subsequently * does a push or arraycat. */ @@ -191,7 +191,7 @@ APR_DECLARE(apr_array_header_t *) apr_array_copy(apr_pool_t *p, * @param p The pool to allocate the copy of the array out of * @param arr The array to copy * @return An exact copy of the array passed in - * @remark The alternate apr_array_copy copies the *entire* array. + * @remark The alternate apr_array_copy() copies the *entire* array. */ APR_DECLARE(apr_array_header_t *) apr_array_copy_hdr(apr_pool_t *p, const apr_array_header_t *arr); @@ -318,7 +318,7 @@ APR_DECLARE(void) apr_table_unset(apr_table_t *t, const char *key); * @param t The table to search for the data * @param key The key to merge data for (case does not matter) * @param val The data to add - * @remark If the key is not found, then this function acts like apr_table_add + * @remark If the key is not found, then this function acts like apr_table_add() */ APR_DECLARE(void) apr_table_merge(apr_table_t *t, const char *key, const char *val); @@ -330,7 +330,7 @@ APR_DECLARE(void) apr_table_merge(apr_table_t *t, const char *key, * @param t The table to search for the data * @param key The key to merge data for (case does not matter) * @param val The data to add - * @remark If the key is not found, then this function acts like apr_table_addn + * @remark If the key is not found, then this function acts like apr_table_addn() */ APR_DECLARE(void) apr_table_mergen(apr_table_t *t, const char *key, const char *val); -- cgit v1.2.1