Document all of the public APR structures with DocBook.

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

10 files changed, 149 insertions, 38 deletions

diff --git a/include/apr_file_io.h b/include/apr_file_io.h
index 32ae5eb74..984c0ab73 100644
--- a/include/apr_file_io.h
+++ b/include/apr_file_io.h
@@ -117,16 +117,34 @@ typedef gid_t                    apr_gid_t;
 typedef ino_t                    apr_ino_t;
 typedef dev_t                    apr_dev_t;
 
+/**
+ * The file information structure.  This is analogous to the POSIX
+ * stat structure.
+ */
 struct apr_finfo_t {
+    /** The access permissions of the file.  Currently this mimics Unix
+     *  access rights.
+     */
     apr_fileperms_t protection;
+    /** The type of file.  One of APR_NOFILE, APR_REG, APR_DIR, APR_CHR, 
+     *  APR_BLK, APR_PIPE, APR_LNK, APR_SOCK 
+     */
     ap_filetype_e filetype;
+    /** The user id that owns the file */
     apr_uid_t user;
+    /** The group id that owns the file */
     apr_gid_t group;
+    /** The inode of the file.  (Not portable?) */
     apr_ino_t inode;
+    /** The id of the device the file is on.  (Not portable?) */
     apr_dev_t device;
+    /** The size of the file */
     apr_off_t size;
+    /** The time the file was last accessed */
     apr_time_t atime;
+    /** The time the file was last modified */
     apr_time_t mtime;
+    /** The time the file was last changed */
     apr_time_t ctime;
 };
 
diff --git a/include/apr_general.h b/include/apr_general.h
index 33b9e3496..1671ef16e 100644
--- a/include/apr_general.h
+++ b/include/apr_general.h
@@ -272,25 +272,45 @@ apr_status_t apr_generate_random_bytes(unsigned char * buf, int length);
 #define ALLOC_STATS
 */
 
-typedef struct apr_pool_t {
+typedef struct apr_pool_t apr_pool_t;
+
+/** The memory allocation structure
+ */
+struct apr_pool_t {
+    /** The first block in this pool. */
     union block_hdr *first;
+    /** The last block in this pool. */
     union block_hdr *last;
+    /** The list of cleanups to run on pool cleanup. */
     struct cleanup *cleanups;
+    /** A list of processes to kill when this pool is cleared */
     struct process_chain *subprocesses;
+    /** The first sub_pool of this pool */
     struct apr_pool_t *sub_pools;
+    /** The next sibling pool */
     struct apr_pool_t *sub_next;
+    /** The previous sibling pool */
     struct apr_pool_t *sub_prev;
+    /** The parent pool of this pool */
     struct apr_pool_t *parent;
+    /** The first free byte in this pool */
     char *free_first_avail;
 #ifdef ALLOC_USE_MALLOC
+    /** The allocation list if using malloc */
     void *allocation_list;
 #endif
 #ifdef POOL_DEBUG
+    /** a list of joined pools 
+     *  @defvar apr_pool_t *joined */
     struct apr_pool_t *joined;
 #endif
+    /** A function to control how pools behave when they receive ENOMEM
+     *  @deffunc int apr_abort(int retcode) */
     int (*apr_abort)(int retcode);
+    /** A place to hand user data associated with this pool 
+     *  @defvar datastruct *prog_data */
     struct datastruct *prog_data;
-}apr_pool_t;
+};
  
 /* pool functions */
 
diff --git a/include/apr_hash.h b/include/apr_hash.h
index c4be2d980..bab59807b 100644
--- a/include/apr_hash.h
+++ b/include/apr_hash.h
@@ -64,7 +64,7 @@ extern "C" {
 #endif
 
 /**
- * package Hash Tables
+ * @package Hash Tables
  */
 
 #include "apr_pools.h"
@@ -83,6 +83,7 @@ typedef struct apr_hash_index_t apr_hash_index_t;
  * Create a hash table within a pool.
  * @param pool The pool to allocate the hash table out of
  * @return The hash table just created
+ * @deffunc apr_hash_t *apr_make_hash(apr_pool_t *pool)
  */
 APR_EXPORT(apr_hash_t *) apr_make_hash(apr_pool_t *pool);
 
@@ -94,6 +95,7 @@ APR_EXPORT(apr_hash_t *) apr_make_hash(apr_pool_t *pool);
  *             If the length is 0 it is assumed to be strlen(key)+1
  * @param val Value to associate with the key
  * @tip If the value is NULL the hash entry is deleted.
+ * @deffunc void apr_hash_set(apr_hash_t *ht, const void *key, size_t klen, const void *val)
  */
 APR_EXPORT(void) apr_hash_set(apr_hash_t *ht, const void *key, size_t klen, 
                              const void *val);
@@ -105,6 +107,7 @@ APR_EXPORT(void) apr_hash_set(apr_hash_t *ht, const void *key, size_t klen,
  * @param klen Length of the key
  *         If the length is 0 it is assumed to be strlen(key)+1
  * @return Returns NULL if the key is not present.
+ * @deffunc void *apr_hash_get(apr_hash_t *ht, const void *key, size_t klen)
  */
 APR_EXPORT(void) *apr_hash_get(apr_hash_t *ht, const void *key, size_t klen);
 
@@ -132,6 +135,7 @@ APR_EXPORT(void) *apr_hash_get(apr_hash_t *ht, const void *key, size_t klen);
  * is delete the current entry) and multiple iterations can be in
  * progress at the same time.
  * </PRE>
+ * @deffunc apr_hash_index_t * apr_hash_first(apr_hash_t *ht)
  */
 APR_EXPORT(apr_hash_index_t *) apr_hash_first(apr_hash_t *ht);
 
@@ -139,6 +143,7 @@ APR_EXPORT(apr_hash_index_t *) apr_hash_first(apr_hash_t *ht);
  * Continue iterating over the entries in a hash table.
  * @param hi The iteration state
  * @return a pointer to the updated iteration state.  NULL if there are no more  *         entries.
+ * @deffunc apr_hash_index_t * apr_hash_next(apr_hash_index_t *hi)
  */
 APR_EXPORT(apr_hash_index_t *) apr_hash_next(apr_hash_index_t *hi);
 
@@ -150,6 +155,7 @@ APR_EXPORT(apr_hash_index_t *) apr_hash_next(apr_hash_index_t *hi);
  * @param val Return pointer for the associated value.
  * @tip The return pointers should point to a variable that will be set to the
  *      corresponding data, or they may be NULL if the data isn't interesting.
+ * @deffunc void apr_hash_this(apr_hash_index_t *hi, const void **key, size_t *klen, void **val);
  */
 APR_EXPORT(void) apr_hash_this(apr_hash_index_t *hi, const void **key, 
                               size_t *klen, void **val);
diff --git a/include/apr_md5.h b/include/apr_md5.h
index 412f1a7a1..d62eb0374 100644
--- a/include/apr_md5.h
+++ b/include/apr_md5.h
@@ -100,16 +100,21 @@ extern "C" {
 
 /* UINT4 defines a four byte word */
 typedef unsigned int UINT4;
-
-/* MD5 context. */
-typedef struct {
-    UINT4 state[4];		/* state (ABCD) */
-    UINT4 count[2];		/* number of bits, modulo 2^64 (lsb first) */
-    unsigned char buffer[64];	/* input buffer */
+typedef struct ap_md5_ctx_t ap_md5_ctx_t;
+
+/** MD5 context. */
+struct ap_md5_ctx_t {
+    /** state (ABCD) */
+    UINT4 state[4];
+    /** number of bits, modulo 2^64 (lsb first) */
+    UINT4 count[2];
+    /** input buffer */
+    unsigned char buffer[64];
 #if APR_HAS_XLATE
-    apr_xlate_t *xlate;          /* translation handle */
+    /** translation handle */
+    apr_xlate_t *xlate;
 #endif
-} ap_md5_ctx_t;
+};
 
 /**
  * MD5 Initialize.  Begins an MD5 operation, writing a new context.
diff --git a/include/apr_mmap.h b/include/apr_mmap.h
index 7b57a50f8..5f47ebd5b 100644
--- a/include/apr_mmap.h
+++ b/include/apr_mmap.h
@@ -75,12 +75,17 @@ typedef struct apr_mmap_t            apr_mmap_t;
  * sense to keep it private, and opening it up makes some stuff easier in
  * Apache.
  */
+/** The MMAP structure */
 struct apr_mmap_t {
+    /** The pool the mmap structure was allocated out of. */
     apr_pool_t *cntxt;
 #ifdef BEOS
+    /** An area ID.  Only valid on BeOS */
     area_id area;
 #endif
+    /** The start of the memory mapped area */
     void *mm;
+    /** The amount of data in the mmap */
     size_t size;
 };
 
diff --git a/include/apr_network_io.h b/include/apr_network_io.h
index c41922746..87e9bb377 100644
--- a/include/apr_network_io.h
+++ b/include/apr_network_io.h
@@ -131,11 +131,17 @@ typedef struct in_addr      apr_in_addr;
 /* Define flags passed in on apr_sendfile() */
 #define APR_SENDFILE_DISCONNECT_SOCKET      1
 
-/* A structure to encapsulate headers and trailers for apr_sendfile */
+/** A structure to encapsulate headers and trailers for apr_sendfile */
 struct apr_hdtr_t {
+    /** An iovec to store the headers sent before the file. 
+     *  @defvar iovec *headers */
     struct iovec* headers;
+    /** number of headers in the iovec */
     int numheaders;
+    /** An iovec to store the trailers sent before the file. 
+     *  @defvar iovec *trailers */
     struct iovec* trailers;
+    /** number of trailers in the iovec */
     int numtrailers;
 };
 #endif
diff --git a/include/apr_pools.h b/include/apr_pools.h
index 75df3e01c..80a5dc6d9 100644
--- a/include/apr_pools.h
+++ b/include/apr_pools.h
@@ -102,9 +102,20 @@ enum kill_conditions {
     kill_only_once              /* send SIGTERM and then wait */
 };
 
+/** A list of processes */
 struct process_chain {
+    /** The process ID */
     apr_proc_t *pid;
+    /** When the process should be sent a signal. <PRE>
+     *           kill_never   -- process is never sent any signals
+     *           kill_always  -- process is sent SIGKILL on apr_pool_t cleanup
+     *           kill_after_timeout -- SIGTERM, wait 3 seconds, SIGKILL
+     *           just_wait    -- wait forever for the process to complete
+     *           kill_only_once -- send SIGTERM and then wait </PRE>
+     */
     enum kill_conditions kill_how;
+    /** The next process in the list 
+     *  @defvar process_chain *next */
     struct process_chain *next;
 };
 
diff --git a/include/apr_tables.h b/include/apr_tables.h
index 837f4bcad..43607d5e8 100644
--- a/include/apr_tables.h
+++ b/include/apr_tables.h
@@ -74,38 +74,58 @@ extern "C" {
  * Define the structures used by the APR general-purpose library.
  */
 
+/**
+ * @package APR Table library
+ */
+
 /*
  * Memory allocation stuff, like pools, arrays, and tables.  Pools
  * and tables are opaque structures to applications, but arrays are
  * published.
  */
 typedef struct apr_table_t apr_table_t;
-typedef struct apr_array_header_t {
+typedef struct apr_array_header_t apr_array_header_t;
+
+/** An opaque array type */
+struct apr_array_header_t {
+    /** The pool the array is allocated out of */
     apr_pool_t *cont;
+    /** The amount of memory allocated for each element of the array */
     int elt_size;
+    /** The number of active elements in the array */
     int nelts;
+    /** The number of elements allocated in the array */
     int nalloc;
+    /** The elements in the array */
     char *elts;
-} apr_array_header_t;
+};
 
+/** The opaque table type */
 struct apr_table_t {
     /* This has to be first to promote backwards compatibility with
      * older modules which cast a apr_table_t * to an apr_array_header_t *...
      * they should use the table_elts() function for most of the
      * cases they do this for.
      */
+    /** The underlying array for the table */
     apr_array_header_t a;
 #ifdef MAKE_TABLE_PROFILE
+    /** Who created the array. */
     void *creator;
 #endif
 };
 
-typedef struct apr_table_entry_t {
+typedef struct apr_table_entry_t apr_table_entry_t;
+
+/** The type for each entry in a table */
+struct apr_table_entry_t {
+    /** The key for the current table entry */
     char *key;          /* maybe NULL in future;
                          * check when iterating thru table_elts
                          */
+    /** The value for the current table entry */
     char *val;
-} apr_table_entry_t;
+};
 
 /* XXX: these know about the definition of struct apr_table_t in alloc.c.  That
  * definition is not here because it is supposed to be private, and by not
diff --git a/include/apr_thread_proc.h b/include/apr_thread_proc.h
index d9d94d773..8cbbf5553 100644
--- a/include/apr_thread_proc.h
+++ b/include/apr_thread_proc.h
@@ -99,12 +99,19 @@ typedef enum {APR_WAIT, APR_NOWAIT} apr_wait_how_e;
                                            * us knowing ... buggy os? */
 #endif /* APR_HAS_OTHER_CHILD */
 
-typedef struct apr_proc_t {
+typedef struct apr_proc_t apr_proc_t;
+
+/** The APR process type */
+struct apr_proc_t {
+    /** The process ID */
     pid_t pid;
-    apr_file_t *in;          /* Parent's side of pipe to child's stdin */
-    apr_file_t *out;         /* Parent's side of pipe to child's stdout */
-    apr_file_t *err;         /* Parent's side of pipe to child's stdouterr */
-} apr_proc_t;
+    /** Parent's side of pipe to child's stdin */
+    apr_file_t *in;
+    /** Parent's side of pipe to child's stdout */
+    apr_file_t *out;
+    /* Parent's side of pipe to child's stdouterr */
+    apr_file_t *err;
+};
 
 typedef struct apr_thread_t           apr_thread_t;
 typedef struct apr_threadattr_t       apr_threadattr_t;
diff --git a/include/apr_time.h b/include/apr_time.h
index aea367c74..16cf10709 100644
--- a/include/apr_time.h
+++ b/include/apr_time.h
@@ -92,23 +92,36 @@ typedef apr_int32_t apr_interval_time_t;
  */
 apr_time_t apr_now(void);
 
-/* a structure similar to ANSI struct tm with the following differences:
-   - tm_usec isn't an ANSI field
-   - tm_gmtoff isn't an ANSI field (it's a bsdism)
-*/
-typedef struct {
-    apr_int32_t tm_usec;	/* microseconds past tm_sec */
-    apr_int32_t tm_sec;	/* (0-61) seconds past tm_min */
-    apr_int32_t tm_min;  /* (0-59) minutes past tm_hour */
-    apr_int32_t tm_hour; /* (0-23) hours past midnight */
-    apr_int32_t tm_mday; /* (1-31) day of the month */
-    apr_int32_t tm_mon;  /* (0-11) month of the year */
-    apr_int32_t tm_year; /* year since 1900 */
-    apr_int32_t tm_wday; /* (0-6) days since sunday */
-    apr_int32_t tm_yday; /* (0-365) days since jan 1 */
-    apr_int32_t tm_isdst; /* daylight saving time */
-    apr_int32_t tm_gmtoff; /* seconds east of UTC */
-} ap_exploded_time_t;
+typedef struct ap_exploded_time_t ap_exploded_time_t;
+/**
+ * a structure similar to ANSI struct tm with the following differences:
+ *  - tm_usec isn't an ANSI field
+ *  - tm_gmtoff isn't an ANSI field (it's a bsdism)
+ */
+struct ap_exploded_time_t {
+    /** microseconds past tm_sec */
+    apr_int32_t tm_usec;
+    /** (0-61) seconds past tm_min */
+    apr_int32_t tm_sec;
+    /** (0-59) minutes past tm_hour */
+    apr_int32_t tm_min;
+    /** (0-23) hours past midnight */
+    apr_int32_t tm_hour;
+    /** (1-31) day of the month */
+    apr_int32_t tm_mday;
+    /** (0-11) month of the year */
+    apr_int32_t tm_mon;
+    /** year since 1900 */
+    apr_int32_t tm_year;
+    /** (0-6) days since sunday */
+    apr_int32_t tm_wday;
+    /** (0-365) days since jan 1 */
+    apr_int32_t tm_yday;
+    /** daylight saving time */
+    apr_int32_t tm_isdst;
+    /** seconds east of UTC */
+    apr_int32_t tm_gmtoff;
+};
 
 /**
  * convert an ansi time_t to an apr_time_t