Doxygen Fixes

Remove Doxygen warnings about undocument structures/defines
apr_hooks stills needs a proper explantion about what APR_HOOK_LINK
and APR_IMPLEMENT_EXTERNAL_BASE do.


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

4 files changed, 41 insertions, 10 deletions

diff --git a/include/apr_dbm.h b/include/apr_dbm.h
index 599cb28a..65b49885 100644
--- a/include/apr_dbm.h
+++ b/include/apr_dbm.h
@@ -66,29 +66,30 @@ extern "C" {
 #endif
 
 /**
- * @package APR-UTIL DBM library
+ * @file apr_dbm.h
+ * @brief APR-UTIL DBM library
  */
 
 /**
  * Structure for referencing a dbm
- * @defvar apr_dbm_t
  */
 typedef struct apr_dbm_t apr_dbm_t;
 
 /**
  * Structure for referencing the datum record within a dbm
- * @defvar apr_datum_t
  */
 typedef struct
 {
+    /** pointer to the 'data' to retrieve/store in the DBM */
     char *dptr;
+    /** size of the 'data' to retreive/store in the DBM */
     apr_size_t dsize;
 } apr_datum_t;
 
 /* modes to open the DB */
-#define APR_DBM_READONLY        1       /* open for read-only access */
-#define APR_DBM_READWRITE       2       /* open for read-write access */
-#define APR_DBM_RWCREATE        3       /* open for r/w, create if needed */
+#define APR_DBM_READONLY        1       /**< open for read-only access */
+#define APR_DBM_READWRITE       2       /**< open for read-write access */
+#define APR_DBM_RWCREATE        3       /**< open for r/w, create if needed */
 
 /**
  * Open a dbm file by file name
diff --git a/include/apr_hooks.h b/include/apr_hooks.h
index 2da7c543..01617ae3 100644
--- a/include/apr_hooks.h
+++ b/include/apr_hooks.h
@@ -68,9 +68,11 @@ extern "C" {
  * @brief Apache hook functions
  */
 
+/** macro to return the prototype of the hook function */    
 #define APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
 link##_DECLARE(apr_array_header_t *) ns##_hook_get_##name(void)
 
+/** macro to declare the hook correctly */    
 #define APR_DECLARE_EXTERNAL_HOOK(ns,link,ret,name,args) \
 typedef ret ns##_HOOK_##name##_t args; \
 link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf, \
@@ -87,6 +89,7 @@ typedef struct ns##_LINK_##name##_t \
     int nOrder; \
     } ns##_LINK_##name##_t;
 
+/** macro to declare the hook structure */    
 #define APR_HOOK_STRUCT(members) \
 static struct { members } _hooks;
 
@@ -216,11 +219,16 @@ link##_DECLARE(ret) ns##_run_##name args_decl \
     return decline; \
     }
 
-     /* Hook orderings */
+    /* Hook orderings */
+/** run this hook first, before ANYTHING */
 #define APR_HOOK_REALLY_FIRST	(-10)
+/** run this hook first */
 #define APR_HOOK_FIRST		0
+/** run this hook somewhere */
 #define APR_HOOK_MIDDLE		10
+/** run this hook after every other hook which is defined*/
 #define APR_HOOK_LAST		20
+/** run this hook last, after EVERYTHING */
 #define APR_HOOK_REALLY_LAST	30
 
 /**
diff --git a/include/apr_optional_hooks.h b/include/apr_optional_hooks.h
index afb92fba..b0b95ab5 100644
--- a/include/apr_optional_hooks.h
+++ b/include/apr_optional_hooks.h
@@ -66,6 +66,19 @@ extern "C" {
  * @brief Apache optional hook functions
  */
 
+/**
+ * Function to implemnt the APR_OPTIONAL_HOOK Macro
+ * @internal
+ * @see APR_OPTIONAL_HOOOK
+ *
+ * @param name The name of the hook
+ * @param pfn A pointer to a function that will be called
+ * @param aszPre a NULL-terminated array of strings that name modules whose hooks should precede this one
+ * @param aszSucc a NULL-terminated array of strings that name modules whose hooks should succeed this one
+ * @param nOrder an integer determining order before honouring aszPre and aszSucc (for example HOOK_MIDDLE)
+ */
+
+
 APU_DECLARE(void) apr_optional_hook_add(const char *szName,void (*pfn)(void),
 					const char * const *aszPre,
 					const char * const *aszSucc,
@@ -86,6 +99,12 @@ APU_DECLARE(void) apr_optional_hook_add(const char *szName,void (*pfn)(void),
 	       const char * const *,int))&apr_optional_hook_add)(#name,pfn,aszPre, \
 							   aszSucc, nOrder)
 
+/**
+ * @internal
+ * return the hook structure for a give hook
+ * @param szName - the name of the function
+ */
+ 
 APU_DECLARE(apr_array_header_t *) apr_optional_hook_get(const char *szName);
 
 /**
diff --git a/include/apr_sha1.h b/include/apr_sha1.h
index d97e98dc..de59f45a 100644
--- a/include/apr_sha1.h
+++ b/include/apr_sha1.h
@@ -70,9 +70,10 @@ extern "C" {
 
 /**
  * @file apr_sha1.h
- * @brief SHA1 library
+ * @brief APR-UTIL SHA1 library
  */
 
+/** size of the SHA1 DIGEST */
 #define APR_SHA1_DIGESTSIZE 20
 
 /**
@@ -80,13 +81,15 @@ extern "C" {
  * hashed using our algorithm.
  */
 #define APR_SHA1PW_ID "{SHA}"
-#define APR_SHA1PW_IDLEN 5
 
-typedef struct apr_sha1_ctx_t apr_sha1_ctx_t;
+/** length of the SHA Password */
+#define APR_SHA1PW_IDLEN 5
 
 /**
  * SHA1 context structure
  */
+typedef struct apr_sha1_ctx_t apr_sha1_ctx_t;
+
 struct apr_sha1_ctx_t {
     /** message digest */
     apr_uint32_t digest[5];