Fix some warnings from doxygen.

Some trailing-whitespace changes are not documented below.

* docs/doxygen.conf
  (DOT_GRAPH_MAX_NODES): Add option. Doxygen 1.9 default is 50 but some headers
                         need more nodes.
* include/apr_general.h,
  include/apr_random.h
  (@defgroup apr_random): Unify title to PRNG Functions.
* include/apr_ldap.h
  (apr_ldap_prepare): Remove non-existing @param err.
* include/apr_memcache.h
  (apr_memcache_add_multget_key): Remove empty @return for void function.
* include/apr_network_io.h
  (apr_sockaddr_ip_getbuf): Document @param buf and @param buflen.
* include/apr_rmm.h
  (apr_rmm_init): Use @A to decorate parameters in text.
* include/apr_thread_proc.h
  (apr_child_errfn_t): Rename parameter proc to pool to better reflect content.
  (apr_thread_current): Change from @param to @return for the return value.
  (apr_thread_name_get): Use @A to decorate parameters in text.
                         Change the documented name of the third parameter to
                         match declaration.
  (apr_thread_name_set): Use @A to decorate parameters in text.
                         Change the documented name of the third parameter to
                         match declaration.
* include/private/apr_encode_private.h
  (@defgroup APR_Util_Encode_Private): Add a title to the group.


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

Author: dsahlberg-apache-org

docs/doxygen.conf

@@ -41,3 +41,4 @@ EXCLUDE_PATTERNS="*/acconfig.h" \
 
 GENERATE_TAGFILE=docs/dox/apr.tag
 
+DOT_GRAPH_MAX_NODES=99

include/apr_general.h

@@ -239,7 +239,7 @@ APR_DECLARE(void) apr_terminate2(void);
 /** @} */
 
 /**
- * @defgroup apr_random Random Functions
+ * @defgroup apr_random PRNG Functions
  * @{
  */
 

include/apr_ldap.h

@@ -124,7 +124,7 @@ typedef struct apr_ldap_url_desc_t {
  * @see apr_ldap_url_parse()
  */
 #define APR_LDAP_URL_ERR_MEM          0x01
-/** 
+/**
  * Parameter is bad
  * @see apr_ldap_url_parse()
  */
@@ -134,37 +134,37 @@ typedef struct apr_ldap_url_desc_t {
  * @see apr_ldap_url_parse()
  */
 #define APR_LDAP_URL_ERR_BADSCHEME    0x03
-/** 
+/**
  * URL is missing trailing ">"
  * @see apr_ldap_url_parse()
  */
 #define APR_LDAP_URL_ERR_BADENCLOSURE 0x04
-/** 
+/**
  * URL is bad
  * @see apr_ldap_url_parse()
  */
 #define APR_LDAP_URL_ERR_BADURL       0x05
-/** 
+/**
  * Host port is bad
  * @see apr_ldap_url_parse()
  */
 #define APR_LDAP_URL_ERR_BADHOST      0x06
-/** 
+/**
  * Bad (or missing) attributes
  * @see apr_ldap_url_parse()
  */
 #define APR_LDAP_URL_ERR_BADATTRS     0x07
-/** 
+/**
  * Scope string is invalid (or missing)
  * @see apr_ldap_url_parse()
  */
 #define APR_LDAP_URL_ERR_BADSCOPE     0x08
-/** 
+/**
  * Bad or missing filter
  * @see apr_ldap_url_parse()
  */
 #define APR_LDAP_URL_ERR_BADFILTER    0x09
-/** 
+/**
  * Bad or missing extensions
  * @see apr_ldap_url_parse()
  */
@@ -459,7 +459,7 @@ typedef enum {
 
 /**
  * LDAP deref settings
- *  
+ *
  * @see apr_ldap_option_set
  * @see APR_LDAP_OPT_DEREF
  */
@@ -472,7 +472,7 @@ typedef enum {
 
 /**
  * LDAP options on or off
- *  
+ *
  * @see apr_ldap_option_set
  * @see APR_LDAP_OPT_REFERRALS
  */
@@ -808,7 +808,7 @@ typedef union apr_ldap_opt_t {
      * Timeouts
      *
      * @see APR_LDAP_OPT_NETWORK_TIMEOUT
-     * @see APR_LDAP_OPT_TIMEOUT     
+     * @see APR_LDAP_OPT_TIMEOUT
      */
     apr_interval_time_t timeout;
     /**
@@ -877,7 +877,7 @@ typedef union apr_ldap_opt_t {
  * @see APR_LDAP_OPT_PROTOCOL_VERSION
  * @see APR_LDAP_OPT_REFERRALS
  * @see APR_LDAP_OPT_REFHOPLIMIT
- * @see APR_LDAP_OPT_RESULT_CODE     
+ * @see APR_LDAP_OPT_RESULT_CODE
  * @see APR_LDAP_OPT_TIMEOUT
  */
 APU_DECLARE_LDAP(apr_status_t) apr_ldap_option_get(apr_pool_t *pool, apr_ldap_t *ldap,
@@ -1183,7 +1183,7 @@ typedef struct apr_ldap_bind_interact_t {
  *
  * @see apr_ldap_bind_interact_t
  * @see apr_ldap_bind
- */ 
+ */
 typedef apr_status_t (apr_ldap_bind_interact_cb)(
         apr_ldap_t *ld, unsigned int flags, apr_ldap_bind_interact_t *interact, void *ctx);
 
@@ -1208,8 +1208,8 @@ typedef apr_status_t (apr_ldap_rebind_proc)(
 
 
 /**
- * APR LDAP connect function. 
- *  
+ * APR LDAP connect function.
+ *
  * This function makes an attempt to connect to the server initialised
  * by apr_ldap_initialise().
  *
@@ -1245,7 +1245,7 @@ APU_DECLARE_LDAP(apr_status_t) apr_ldap_connect(apr_pool_t *pool,
  */
 typedef apr_status_t (*apr_ldap_prepare_cb)(apr_ldap_t *ldap, apr_status_t status,
                                             void *ctx, apu_err_t *err);
- 
+
 
 /**
  * APR LDAP prepare function
@@ -1265,7 +1265,6 @@ typedef apr_status_t (*apr_ldap_prepare_cb)(apr_ldap_t *ldap, apr_status_t statu
  * next called this callback will be triggered in the expectation of the next
  * LDAP request.
  * @param prepare_ctx Context passed to the prepare callback.
- * @param err Error structure for reporting detailed results.
  *
  * @return APR_SUCCESS means the callback was successfully prepared. Other error
  * codes indicate that the attept to send the cancellation was not successful.
@@ -1321,7 +1320,7 @@ APU_DECLARE_LDAP(apr_status_t) apr_ldap_process(apr_pool_t *pool,
  * @return APR_WANT_WRITE means that at least one further process is outstanding
  * and a further write callback should be scheduled. APR_WANTS_READ indicates
  * more responses are expected and we're waiting for the response. APR_SUCCESS
- * means that no further processing is needed. Other error codes indicate that 
+ * means that no further processing is needed. Other error codes indicate that
  * the processing of outstanding conversations was not successful.
  */
 APU_DECLARE_LDAP(apr_status_t) apr_ldap_result(apr_pool_t *pool,
@@ -1355,7 +1354,7 @@ APU_DECLARE_LDAP(apr_status_t) apr_ldap_poll(apr_pool_t *pool,
                                              __attribute__((nonnull(1,2,3,5)));
 
 
-/** 
+/**
  * Callback to receive the results of a bind operation.
  *
  * When a bind is successful, this function is called with a status of
@@ -1381,17 +1380,17 @@ APU_DECLARE_LDAP(apr_status_t) apr_ldap_poll(apr_pool_t *pool,
  * @see apr_ldap_bind
  * @see apr_ldap_process
  * @see apr_ldap_result
- */ 
+ */
 typedef apr_status_t (*apr_ldap_bind_cb)(apr_ldap_t *ldap, apr_status_t status,
                                          const char *matcheddn,
                                          apr_ldap_control_t **serverctrls,
                                          void *ctx, apu_err_t *err);
 
 
 #if 0
-/** 
+/**
  * Function called to report cancel results.
- */ 
+ */
 typedef void (*apr_ldap_cancel_cb)(apr_ldap_t *ldap, apr_ldap_message_t *msg, void *ctx);
 
 /**
@@ -1528,7 +1527,7 @@ typedef apr_status_t (*apr_ldap_compare_cb)(apr_ldap_t *ldap, apr_status_t statu
  * apr_ldap_compare_cb provided.
  *
  * @param pool The pool that keeps track of the lifetime of the compare conversation.
- * If this pool is cleaned up, the compare conversation will be gracefully 
+ * If this pool is cleaned up, the compare conversation will be gracefully
  * abandoned without affecting other LDAP requests in progress. This pool need
  * not have any relationship with the LDAP connection pool.
  * @param ldap The ldap handle
@@ -1538,7 +1537,7 @@ typedef apr_status_t (*apr_ldap_compare_cb)(apr_ldap_t *ldap, apr_status_t statu
  * terminated text, or binary.
  * @param serverctrls NULL terminated array of server controls.
  * @param clientctrls NULL terminated array of client controls.
- * @param timeout The timeout to use for writes. 
+ * @param timeout The timeout to use for writes.
  * @param compare_cb The compare result callback function. When the compare process has
  * completed the success or failure of the compare is returned here. The callback
  * is triggered from inside apr_ldap_process() so that it is safe to write the
@@ -1646,7 +1645,7 @@ typedef struct apr_ldap_search_entry_t {
  * and then once for each entry to indicate the entry is complete.
  *
  * When complete, return APR_SUCCESS to indicate you want to continue, or
- * a different code if you want the event loop to give up. This code will 
+ * a different code if you want the event loop to give up. This code will
  * be returned from apr_ldap_result().
  *
  * @see apr_ldap_search
@@ -1660,9 +1659,9 @@ typedef apr_status_t (*apr_ldap_search_entry_cb)(apr_ldap_t *ldap, const char *d
 
 /**
  * APR LDAP search function
- *      
+ *
  * This function searches a previously initialised LDAP connection to the directory.
- *  
+ *
  * Searches are attempted asynchronously. For non blocking behaviour, this function
  * must be called after the underlying socket has indicated that it is ready to
  * write.
@@ -2235,4 +2234,3 @@ APU_DECLARE_LDAP(apr_status_t) apr_ldap_unbind(apr_ldap_t *ldap,
 #endif /* APU_HAS_LDAP */
 /** @} */
 #endif /* APU_LDAP_H */
-

include/apr_memcache.h

@@ -288,7 +288,6 @@ APR_DECLARE(apr_status_t) apr_memcache_getp(apr_memcache_t *mc,
  * @param data_pool pool from where the hash and their items are created from
  * @param key null terminated string containing the key
  * @param values hash of keys and values that this key will be added to
- * @return
  */
 APR_DECLARE(void) apr_memcache_add_multget_key(apr_pool_t *data_pool,
                                                const char* key,

include/apr_network_io.h

@@ -779,6 +779,9 @@ APR_DECLARE(apr_status_t) apr_sockaddr_ip_get(char **addr,
 /**
  * Write the IP address (in numeric address string format) of the APR
  * socket address @a sockaddr into the buffer @a buf (of size @a buflen).
+ * @param buf A buffer to store the IP address in.
+ * @param buflen The length of @a buf.  Must be enough to store the IP address,
+ *               otherwise APR_ENOSPC will be returned.
  * @param sockaddr The socket address to reference.
  */
 APR_DECLARE(apr_status_t) apr_sockaddr_ip_getbuf(char *buf, apr_size_t buflen,
@@ -954,4 +957,3 @@ APR_DECLARE(apr_status_t) apr_mcast_interface(apr_socket_t *sock,
 #endif
 
 #endif  /* ! APR_NETWORK_IO_H */
-

include/apr_random.h

@@ -30,7 +30,7 @@ extern "C" {
 #endif /* __cplusplus */
 
 /**
- * @defgroup apr_random PRNG Routines
+ * @defgroup apr_random PRNG Functions
  * @ingroup APR
  * @{
  */

include/apr_rmm.h

@@ -50,7 +50,7 @@ typedef apr_size_t   apr_rmm_off_t;
  * @param membuf The block of relocatable memory to be managed
  * @param memsize The size of relocatable memory block to be managed
  * @param cont The pool to use for local storage and management
- * @remark Both @param membuf and @param memsize must be aligned
+ * @remark Both @a membuf and @a memsize must be aligned
  * (for instance using APR_ALIGN_DEFAULT).
  */
 APR_DECLARE(apr_status_t) apr_rmm_init(apr_rmm_t **rmm, apr_anylock_t *lock,
@@ -134,4 +134,3 @@ APR_DECLARE(apr_size_t) apr_rmm_overhead_get(int n);
 #endif
 /** @} */
 #endif  /* ! APR_RMM_H */
-

include/apr_thread_proc.h

@@ -171,7 +171,7 @@ typedef struct apr_proc_t {
  * @param err APR error code describing the error
  * @param description Text description of type of processing which failed
  */
-typedef void (apr_child_errfn_t)(apr_pool_t *proc, apr_status_t err,
+typedef void (apr_child_errfn_t)(apr_pool_t *pool, apr_status_t err,
                                  const char *description);
 
 /** Opaque Thread structure. */
@@ -281,7 +281,7 @@ APR_DECLARE(apr_status_t) apr_threadattr_guardsize_set(apr_threadattr_t *attr,
  * Set the threshold at which the thread pool allocator should start
  * giving blocks back to the system.
  * @param attr The threadattr to affect
- * @param on Non-zero if detached threads should be created.
+ * @param size Non-zero if detached threads should be created.
  */
 APR_DECLARE(apr_status_t) apr_threadattr_max_free_set(apr_threadattr_t *attr,
                                                       apr_size_t size);
@@ -318,8 +318,8 @@ APR_DECLARE(void) apr_thread_current_after_fork(void);
 
 /**
  * Get the current thread
- * @param The current apr_thread, NULL if it is not an apr_thread or if
- *        it could not be determined.
+ * @return The current apr_thread, NULL if it is not an apr_thread or if
+ *         it could not be determined.
  */
 APR_DECLARE(apr_thread_t *) apr_thread_current(void);
 
@@ -343,8 +343,8 @@ APR_DECLARE(apr_status_t) apr_thread_join(apr_status_t *retval,
  * Get name of thread
  * @param name The variable where is will be stored name of thread.
  * @param thread The thread that name required to get.
- * Current thread will be used if @param thread is NULL.
- * @param cont The pool to use
+ * Current thread will be used if @a thread is NULL.
+ * @param pool The pool to use
  */
 APR_DECLARE(apr_status_t) apr_thread_name_get(char **name,
                                               apr_thread_t *thread,
@@ -355,8 +355,8 @@ APR_DECLARE(apr_status_t) apr_thread_name_get(char **name,
  * @param name The name of thread must be setted. If name is to long, then
  * name stripped to max length supported by operation system.
  * @param thread The thread that name will be changed.
- * Current thread will be used if @param thread is NULL.
- * @param cont The pool to use for temporary allocations
+ * Current thread will be used if @a thread is NULL.
+ * @param pool The pool to use for temporary allocations
  */
 APR_DECLARE(apr_status_t) apr_thread_name_set(const char *name,
                                               apr_thread_t *thread,
@@ -919,4 +919,3 @@ APR_POOL_DECLARE_ACCESSOR(thread);
 #endif
 
 #endif  /* ! APR_THREAD_PROC_H */
-

include/private/apr_encode_private.h

@@ -28,7 +28,7 @@ extern "C" {
 #endif
 
 /**
- * @defgroup APR_Util_Encode_Private
+ * @defgroup APR_Util_Encode_Private Internal APR encoding functions
  * @ingroup APR_Util
  * @{
  */