A lot of doxygen updates

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@92285 f38db490-d61c-443f-a65b-d21fe96a405b

23 files changed, 195 insertions, 131 deletions

diff --git a/include/asterisk/_private.h b/include/asterisk/_private.h
index a936bea9e..06163cd53 100644
--- a/include/asterisk/_private.h
+++ b/include/asterisk/_private.h
@@ -4,6 +4,14 @@
  * What goes here are typically *_init() routines.
  */
 
+/*! \file
+ *
+ * \brief
+ * Prototypes for public functions only of internal interest,
+ * 
+ */
+
+
 #ifndef _ASTERISK__PRIVATE_H
 #define _ASTERISK__PRIVATE_H
 
diff --git a/include/asterisk/adsi.h b/include/asterisk/adsi.h
index c4379dc88..3c31574a5 100644
--- a/include/asterisk/adsi.h
+++ b/include/asterisk/adsi.h
@@ -24,6 +24,8 @@
 #define _ASTERISK_ADSI_H
 
 #include "asterisk/callerid.h"
+/*! \name ADSI parameters */
+/*@{ */
 
 /* ADSI Message types */
 #define ADSI_MSG_DISPLAY	132
@@ -117,6 +119,8 @@
 #define ADSI_DIR_FROM_LEFT (0)
 #define ADSI_DIR_FROM_RIGHT (1)
 
+/*@} */
+
 /*! Perform Asterisk ADSI initialization (for channel drivers that want 
  *    to support ADSI when the handset is first lifted) 
  * \param chan Channel to initialize for ADSI (if supported)
diff --git a/include/asterisk/ael_structs.h b/include/asterisk/ael_structs.h
index fa551bf91..0a58ed378 100644
--- a/include/asterisk/ael_structs.h
+++ b/include/asterisk/ael_structs.h
@@ -20,6 +20,7 @@
  * \brief Structures for AEL - the Asterisk extension language
  *
  * \ref pbx_ael.c
+ * \todo document this file (ael.h)
  */
 
 #ifndef _ASTERISK_AEL_STRUCTS_H
@@ -113,8 +114,8 @@ struct ael_extension
 	struct ael_priority *plist_last;
 	struct ael_extension *next_exten;
 
-	struct ael_priority *loop_break;  /* set by latest loop for breaks */
-	struct ael_priority *loop_continue; /* set by lastest loop for continuing */
+	struct ael_priority *loop_break;  /*!< set by latest loop for breaks */
+	struct ael_priority *loop_continue; /*!< set by lastest loop for continuing */
 	struct ael_priority *return_target;
 	int return_needed;
 };
diff --git a/include/asterisk/aes.h b/include/asterisk/aes.h
index bf7996806..25e76153f 100644
--- a/include/asterisk/aes.h
+++ b/include/asterisk/aes.h
@@ -17,7 +17,9 @@
  */
 
 /*! \file
- * \brief Wrappers for AES encryption/decryption
+ * Wrappers for AES encryption/decryption
+ *
+ * \author Kevin P. Fleming <kpfleming@digium.com>
  *
  * These wrappers provided a generic interface to either the
  * AES methods provided by OpenSSL's crypto library, or the
diff --git a/include/asterisk/agi.h b/include/asterisk/agi.h
index 1d86ac90b..5085f05df 100644
--- a/include/asterisk/agi.h
+++ b/include/asterisk/agi.h
@@ -28,11 +28,11 @@ extern "C" {
 #endif
 
 typedef struct agi_state {
-	int fd;		/* FD for general output */
-	int audio;	/* FD for audio output */
-	int ctrl;		/* FD for input control */
-	unsigned int fast:1; /* flag for fast agi or not */
-	struct ast_speech *speech; /* Speech structure for speech recognition */
+	int fd;		        /*!< FD for general output */
+	int audio;	        /*!< FD for audio output */
+	int ctrl;		/*!< FD for input control */
+	unsigned int fast:1;    /*!< flag for fast agi or not */
+	struct ast_speech *speech; /*!< Speech structure for speech recognition */
 } AGI;
 
 typedef struct agi_command {
diff --git a/include/asterisk/alaw.h b/include/asterisk/alaw.h
index 34968969d..0ef42becc 100644
--- a/include/asterisk/alaw.h
+++ b/include/asterisk/alaw.h
@@ -24,8 +24,7 @@
 #define _ASTERISK_ALAW_H
 
 
-/*! Init the ulaw conversion stuff */
-/*!
+/*! \brief
  * To init the alaw to slinear conversion stuff, this needs to be run.
  */
 void ast_alaw_init(void);
@@ -37,9 +36,7 @@ void ast_alaw_init(void);
 #define AST_ALAW_AMI_MASK  0x55
 
 
-/*! converts signed linear to alaw */
-/*!
- */
+/*! \brief converts signed linear to alaw */
 #ifndef G711_NEW_ALGORITHM
 extern unsigned char __ast_lin2a[8192];
 #else
@@ -55,7 +52,7 @@ extern short __ast_alaw[256];
 #define AST_LIN2A_LOOKUP(mag)							\
 	__ast_lin2a[(mag) >> AST_ALAW_BIT_LOSS]
 
-/*! convert signed linear sample to sign-magnitude pair for a-Law */
+/*! \brief Convert signed linear sample to sign-magnitude pair for a-Law */
 static inline void ast_alaw_get_sign_mag(short sample, unsigned *sign, unsigned *mag)
 {
 	/* It may look illogical to retrive the sign this way in both cases,
diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index f76b0d96f..26523d4bd 100644
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -17,7 +17,7 @@
 
 /*! \file
  * \brief Application convenience functions, designed to give consistent
- look and feel to Asterisk apps.
+ *        look and feel to Asterisk apps.
  */
 
 #ifndef _ASTERISK_APP_H
@@ -109,16 +109,16 @@ void ast_install_vm_functions(int (*has_voicemail_func)(const char *mailbox, con
   
 void ast_uninstall_vm_functions(void);
 
-/*! Determine if a given mailbox has any voicemail */
+/*! \brief Determine if a given mailbox has any voicemail */
 int ast_app_has_voicemail(const char *mailbox, const char *folder);
 
-/*! Determine number of new/old messages in a mailbox */
+/*! \brief Determine number of new/old messages in a mailbox */
 int ast_app_inboxcount(const char *mailbox, int *newmsgs, int *oldmsgs);
 
-/*! Determine number of messages in a given mailbox and folder */
+/*! \brief Determine number of messages in a given mailbox and folder */
 int ast_app_messagecount(const char *context, const char *mailbox, const char *folder);
 
-/*! Safely spawn an external program while closing file descriptors 
+/*! \brief Safely spawn an external program while closing file descriptors 
 	\note This replaces the \b system call in all Asterisk modules
 */
 int ast_safe_system(const char *s);
@@ -163,7 +163,7 @@ void ast_unreplace_sigchld(void);
 */
 int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between, unsigned int duration);
 
-/*! Stream a filename (or file descriptor) as a generator. */
+/*! \brief Stream a filename (or file descriptor) as a generator. */
 int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, int allowoverride);
 
 /*! 
@@ -171,6 +171,7 @@ int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, in
  * \param chan 
  * \param file filename
  * \param fwd, rev, stop, pause, restart, skipms, offsetms 
+ *
  * Before calling this function, set this to be the number 
  * of ms to start from the beginning of the file.  When the function
  * returns, it will be the number of ms from the beginning where the
@@ -178,23 +179,21 @@ int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, in
  */
 int ast_control_streamfile(struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *pause, const char *restart, int skipms, long *offsetms);
 
-/*! Play a stream and wait for a digit, returning the digit that was pressed */
+/*! \brief Play a stream and wait for a digit, returning the digit that was pressed */
 int ast_play_and_wait(struct ast_channel *chan, const char *fn);
 
 int ast_play_and_record_full(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf);
 
-/*! Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum 
+/*! \brief Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum 
  \n
  permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults. 
      calls ast_unlock_path() on 'path' if passed */
 int ast_play_and_record(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path);
 
-/*! Record a message and prepend the message to the given record file after 
+/*! \brief Record a message and prepend the message to the given record file after 
     playing the optional playfile (or a beep), storing the duration in 
-    'duration' and with a maximum  
-\n
-  permitted silence time in milliseconds of 'maxsilence' under 
-  'silencethreshold' or use '-1' for either or both parameters for defaults. */
+    'duration' and with a maximum permitted silence time in milliseconds of 'maxsilence' under 
+    'silencethreshold' or use '-1' for either or both parameters for defaults. */
 int ast_play_and_prepend(struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int beep, int silencethreshold, int maxsilence_ms);
 
 enum AST_LOCK_RESULT {
@@ -223,42 +222,42 @@ void ast_set_lock_type(enum AST_LOCK_TYPE type);
  */
 enum AST_LOCK_RESULT ast_lock_path(const char *path);
 
-/*! Unlock a path */
+/*! \brief Unlock a path */
 int ast_unlock_path(const char *path);
 
-/*! Read a file into asterisk*/
+/*! \brief Read a file into asterisk*/
 char *ast_read_textfile(const char *file);
 
 struct ast_group_info;
 
-/*! Split a group string into group and category, returning a default category if none is provided. */
+/*! \brief Split a group string into group and category, returning a default category if none is provided. */
 int ast_app_group_split_group(const char *data, char *group, int group_max, char *category, int category_max);
 
-/*! Set the group for a channel, splitting the provided data into group and category, if specified. */
+/*! \brief Set the group for a channel, splitting the provided data into group and category, if specified. */
 int ast_app_group_set_channel(struct ast_channel *chan, const char *data);
 
-/*! Get the current channel count of the specified group and category. */
+/*! \brief Get the current channel count of the specified group and category. */
 int ast_app_group_get_count(const char *group, const char *category);
 
-/*! Get the current channel count of all groups that match the specified pattern and category. */
+/*! \brief Get the current channel count of all groups that match the specified pattern and category. */
 int ast_app_group_match_get_count(const char *groupmatch, const char *category);
 
-/*! Discard all group counting for a channel */
+/*! \brief Discard all group counting for a channel */
 int ast_app_group_discard(struct ast_channel *chan);
 
-/*! Update all group counting for a channel to a new one */
+/*! \brief Update all group counting for a channel to a new one */
 int ast_app_group_update(struct ast_channel *oldchan, struct ast_channel *newchan);
 
-/*! Write Lock the group count list */
+/*! \brief Write Lock the group count list */
 int ast_app_group_list_wrlock(void);
 
-/*! Read Lock the group count list */
+/*! \brief Read Lock the group count list */
 int ast_app_group_list_rdlock(void);
 
-/*! Get the head of the group count list */
+/*! \brief Get the head of the group count list */
 struct ast_group_info *ast_app_group_list_head(void);
 
-/*! Unlock the group count list */
+/*! \brief Unlock the group count list */
 int ast_app_group_list_unlock(void);
 
 /*!
@@ -451,10 +450,10 @@ int ast_app_parse_options64(const struct ast_app_option *options, struct ast_fla
 \note Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */
 int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout);
 
-/*! Allow to record message and have a review option */
+/*! \brief Allow to record message and have a review option */
 int ast_record_review(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime, const char *fmt, int *duration, const char *path);
 
-/*! Decode an encoded control or extended ASCII character */
+/*! \brief Decode an encoded control or extended ASCII character */
 int ast_get_encoded_char(const char *stream, char *result, size_t *consumed);
 
 #if defined(__cplusplus) || defined(c_plusplus)
diff --git a/include/asterisk/ast_expr.h b/include/asterisk/ast_expr.h
index c478281d0..a89b7b9a1 100644
--- a/include/asterisk/ast_expr.h
+++ b/include/asterisk/ast_expr.h
@@ -16,6 +16,13 @@
  * at the top of the source tree.
  */
 
+/*! \file
+ *  
+ *      ???????  
+ *	\todo Explain this file!
+ */
+
+
 #ifndef _ASTERISK_EXPR_H
 #define _ASTERISK_EXPR_H
 #ifndef STANDALONE
diff --git a/include/asterisk/astdb.h b/include/asterisk/astdb.h
index 887d9af5b..e19784bad 100644
--- a/include/asterisk/astdb.h
+++ b/include/asterisk/astdb.h
@@ -33,16 +33,22 @@ struct ast_db_entry {
 	char data[0];
 };
 
+/*! \brief Get key value specified by family/key */
 int ast_db_get(const char *family, const char *key, char *out, int outlen);
 
+/*! \brief Store value addressed by family/key*/
 int ast_db_put(const char *family, const char *key, const char *value);
 
+/*! \brief Delete entry in astdb */
 int ast_db_del(const char *family, const char *key);
 
+/*! \brief Delete a whole family (for some reason also called "tree" */
 int ast_db_deltree(const char *family, const char *keytree);
 
+/*! \brief Get a whole family */
 struct ast_db_entry *ast_db_gettree(const char *family, const char *keytree);
 
+/*! \brief Free in-memory data */
 void ast_db_freetree(struct ast_db_entry *entry);
 
 #if defined(__cplusplus) || defined(c_plusplus)
diff --git a/include/asterisk/astobj2.h b/include/asterisk/astobj2.h
index c19ab683a..b02b6cba8 100644
--- a/include/asterisk/astobj2.h
+++ b/include/asterisk/astobj2.h
@@ -18,8 +18,9 @@
 #define _ASTERISK_ASTOBJ2_H
 
 /*! \file 
+ * \ref AstObj2
  *
- * \brief Object Model implementing objects and containers.
+ * \page AstObj2 Object Model implementing objects and containers.
 
 This module implements an abstraction for objects (with locks and
 reference counts), and containers for these user-defined objects,
@@ -28,7 +29,7 @@ also supporting locking, reference counting and callbacks.
 The internal implementation of objects and containers is opaque to the user,
 so we can use different data structures as needs arise.
 
-USAGE - OBJECTS
+\section AstObj2_UsageObjects USAGE - OBJECTS
 
 An ao2 object is a block of memory that the user code can access,
 and for which the system keeps track (with a bit of help from the
@@ -53,21 +54,21 @@ The value returned points to the user-visible portion of the objects
 operations such as refcount and lock manipulations.
 
 On return from ao2_alloc():
-- the object has a refcount = 1;
 
-- the memory for the object is allocated dynamically and zeroed;
-
-- we cannot realloc() the object itself;
-
-- we cannot call free(o) to dispose of the object. Rather, we
-  tell the system that we do not need the reference anymore:
+ - the object has a refcount = 1;
+ - the memory for the object is allocated dynamically and zeroed;
+ - we cannot realloc() the object itself;
+ - we cannot call free(o) to dispose of the object. Rather, we
+   tell the system that we do not need the reference anymore:
 
     ao2_ref(o, -1)
 
   causing the destructor to be called (and then memory freed) when
   the refcount goes to 0. This is also available as ao2_unref(o),
   and returns NULL as a convenience, so you can do things like
+
 	o = ao2_unref(o);
+
   and clean the original pointer to prevent errors.
 
 - ao2_ref(o, +1) can be used to modify the refcount on the
@@ -77,7 +78,7 @@ On return from ao2_alloc():
   to manipulate the lock associated with the object.
 
 
-USAGE - CONTAINERS
+\section AstObj2_UsageContainers USAGE - CONTAINERS
 
 An ao2 container is an abstract data structure where we can store
 ao2 objects, search them (hopefully in an efficient way), and iterate
@@ -94,7 +95,9 @@ parameters. At the moment, this is done as follows:
 
     c = ao2_container_alloc(MAX_BUCKETS, my_hash_fn, my_cmp_fn);
     \endcode
+
 where
+
 - MAX_BUCKETS is the number of buckets in the hash table,
 - my_hash_fn() is the (user-supplied) function that returns a
   hash key for the object (further reduced modulo MAX_BUCKETS
@@ -129,9 +132,12 @@ reinserting it after the change (this is not terribly expensive).
 \note A container with a single buckets is effectively a linked
 list. However there is no ordering among elements.
 
+- \ref AstObj2_Containers
+- \ref astobj2.h All documentation for functions and data structures
+
  */
 
-/*!
+/*! \brief
  * Typedef for an object destructor. This is called just before freeing
  * the memory for the object. It is passed a pointer to the user-defined
  * data of the object.
@@ -139,7 +145,7 @@ list. However there is no ordering among elements.
 typedef void (*ao2_destructor_fn)(void *);
 
 
-/*!
+/*! \brief
  * Allocate and initialize an object.
  * 
  * \param data_size The sizeof() of the user-defined structure.
@@ -156,7 +162,7 @@ typedef void (*ao2_destructor_fn)(void *);
  */
 void *ao2_alloc(const size_t data_size, ao2_destructor_fn destructor_fn);
 
-/*!
+/*! \brief
  * Reference/unreference an object and return the old refcount.
  *
  * \param o A pointer to the object
@@ -178,7 +184,7 @@ void *ao2_alloc(const size_t data_size, ao2_destructor_fn destructor_fn);
  */
 int ao2_ref(void *o, int delta);
 
-/*!
+/*! \brief
  * Lock an object.
  * 
  * \param a A pointer to the object we want lock.
@@ -186,7 +192,7 @@ int ao2_ref(void *o, int delta);
  */
 int ao2_lock(void *a);
 
-/*!
+/*! \brief
  * Unlock an object.
  * 
  * \param a A pointer to the object we want unlock.
@@ -194,31 +200,31 @@ int ao2_lock(void *a);
  */
 int ao2_unlock(void *a);
 
-/*!
+/*! 
  *
- * Containers
+ \page AstObj2_Containers AstObj2 Containers
 
 Containers are data structures meant to store several objects,
 and perform various operations on them.
 Internally, objects are stored in lists, hash tables or other
 data structures depending on the needs.
 
-NOTA BENE: at the moment the only container we support is the
-hash table and its degenerate form, the list.
+\note NOTA BENE: at the moment the only container we support is the
+	hash table and its degenerate form, the list.
 
 Operations on container include:
 
-    c = ao2_container_alloc(size, cmp_fn, hash_fn)
+  -  c = \b ao2_container_alloc(size, cmp_fn, hash_fn)
 	allocate a container with desired size and default compare
 	and hash function
 
-    ao2_find(c, arg, flags)
+  -  \b ao2_find(c, arg, flags)
 	returns zero or more element matching a given criteria
 	(specified as arg). Flags indicate how many results we
 	want (only one or all matching entries), and whether we
 	should unlink the object from the container.
 
-    ao2_callback(c, flags, fn, arg)
+  -  \b ao2_callback(c, flags, fn, arg)
 	apply fn(obj, arg) to all objects in the container.
 	Similar to find. fn() can tell when to stop, and
 	do anything with the object including unlinking it.
@@ -231,9 +237,11 @@ Operations on container include:
 	can do basically anything e.g. counting, deleting records, etc.
 	possibly using arg to store the results.
    
-    iterate on a container
+  -  \b iterate on a container
 	this is done with the following sequence
 
+\code
+
 	    struct ao2_container *c = ... // our container
 	    struct ao2_iterator i;
 	    void *o;
@@ -244,38 +252,40 @@ Operations on container include:
 		... do something on o ...
 		ao2_ref(o, -1);
 	    }
+\endcode
 
 	The difference with the callback is that the control
 	on how to iterate is left to us.
 
-    ao2_ref(c, -1)
+    - \b ao2_ref(c, -1)
 	dropping a reference to a container destroys it, very simple!
  
 Containers are ao2 objects themselves, and this is why their
 implementation is simple too.
 
- */
+Before declaring containers, we need to declare the types of the
+arguments passed to the constructor - in turn, this requires
+to define callback and hash functions and their arguments.
 
-/*!
- * Before declaring containers, we need to declare the types of the
- * arguments passed to the constructor - in turn, this requires
- * to define callback and hash functions and their arguments.
+- \ref AstObj2
+- \ref astobj2.h
  */
 
-/*!
+/*! \brief
  * Type of a generic callback function
  * \param obj  pointer to the (user-defined part) of an object.
  * \param arg callback argument from ao2_callback()
  * \param flags flags from ao2_callback()
+ *
  * The return values are a combination of enum _cb_results.
  * Callback functions are used to search or manipulate objects in a container,
  */
 typedef int (ao2_callback_fn)(void *obj, void *arg, int flags);
 
-/*! a very common callback is one that matches by address. */
+/*! \brief a very common callback is one that matches by address. */
 ao2_callback_fn ao2_match_by_addr;
 
-/*!
+/*! \brief
  * A callback function will return a combination of CMP_MATCH and CMP_STOP.
  * The latter will terminate the search in a container.
  */
@@ -284,7 +294,7 @@ enum _cb_results {
 	CMP_STOP	= 0x2,	/*!< stop the search now */
 };
 
-/*!
+/*! \brief
  * Flags passed to ao2_callback() and ao2_hash_fn() to modify its behaviour.
  */
 enum search_flags {
@@ -312,12 +322,13 @@ enum search_flags {
  */
 typedef int (ao2_hash_fn)(const void *obj, const int flags);
 
-/*!
+/*! \name Object Containers 
  * Here start declarations of containers.
  */
+/*@{ */
 struct ao2_container;
 
-/*!
+/*! \brief
  * Allocate and initialize a container 
  * with the desired number of buckets.
  * 
@@ -335,17 +346,19 @@ struct ao2_container;
 struct ao2_container *ao2_container_alloc(const uint n_buckets,
 		ao2_hash_fn *hash_fn, ao2_callback_fn *cmp_fn);
 
-/*!
+/*! \brief
  * Returns the number of elements in a container.
  */
 int ao2_container_count(struct ao2_container *c);
+/*@} */
 
-/*
+/*! \name Object Management
  * Here we have functions to manage objects.
  *
  * We can use the functions below on any kind of 
  * object defined by the user.
  */
+/*@{ */
 
 /*!
  * \brief Add an object to a container.
@@ -387,8 +400,9 @@ struct ao2_list {
 	struct ao2_list *next;
 	void *obj;	/* pointer to the user portion of the object */
 };
+/*@} */
 
-/*!
+/*! \brief
  * ao2_callback() is a generic function that applies cb_fn() to all objects
  * in a container, as described below.
  * 
@@ -400,6 +414,7 @@ struct ao2_list {
  * \return 	A pointer to the object found/marked, 
  * 		a pointer to a list of objects matching comparison function,
  * 		NULL if not found.
+ *
  * If the function returns any objects, their refcount is incremented,
  * and the caller is in charge of decrementing them once done.
  * Also, in case of multiple values returned, the list used
@@ -453,7 +468,7 @@ void *ao2_callback(struct ao2_container *c,
  */
 void *ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
 
-/*!
+/*! \brief
  *
  *
  * When we need to walk through a container, we use
@@ -502,8 +517,10 @@ void *ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
  *
  */
 
-/*!
- * You are not supposed to know the internals of an iterator!
+/*! \brief 
+ * The Astobj2 iterator
+ *
+ * \note You are not supposed to know the internals of an iterator!
  * We would like the iterator to be opaque, unfortunately
  * its size needs to be known if we want to store it around
  * without too much trouble.
@@ -513,6 +530,7 @@ void *ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
  * should be locked or not while navigating on it.
  * The iterator "points" to the current object, which is identified
  * by three values:
+ *
  * - a bucket number;
  * - the object_id, which is also the container version number
  *   when the object was inserted. This identifies the object
@@ -521,10 +539,10 @@ void *ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
  * - a pointer, and a container version when we saved the pointer.
  *   If the container has not changed its version number, then we
  *   can safely follow the pointer to reach the object in constant time.
+ *
  * Details are in the implementation of ao2_iterator_next()
  * A freshly-initialized iterator has bucket=0, version = 0.
  */
-
 struct ao2_iterator {
 	/*! the container */
 	struct ao2_container *c;
diff --git a/include/asterisk/callerid.h b/include/asterisk/callerid.h
index b7568c27f..8bf27158b 100644
--- a/include/asterisk/callerid.h
+++ b/include/asterisk/callerid.h
@@ -20,6 +20,8 @@
  * \brief CallerID (and other GR30) management and generation
  * Includes code and algorithms from the Zapata library.
  *
+ * \ref CID
+ *
  */
 
 /*!
diff --git a/include/asterisk/causes.h b/include/asterisk/causes.h
index ad3fa672d..fb4f3c115 100644
--- a/include/asterisk/causes.h
+++ b/include/asterisk/causes.h
@@ -85,7 +85,11 @@ For more information:
 - \ref app_dial.c
 */
 
-/* Causes for disconnection (from Q.931) */
+/*! \name Causes for disconnection (from Q.931) 
+	These are the internal cause codes used in Asterisk.
+	\ref AstCauses
+*/
+/*@{ */
 #define AST_CAUSE_UNALLOCATED				1
 #define AST_CAUSE_NO_ROUTE_TRANSIT_NET			2
 #define AST_CAUSE_NO_ROUTE_DESTINATION			3
@@ -140,5 +144,6 @@ For more information:
 #define AST_CAUSE_UNREGISTERED				AST_CAUSE_NO_ROUTE_DESTINATION
 #define AST_CAUSE_NOTDEFINED 				0
 #define AST_CAUSE_NOSUCHDRIVER				AST_CAUSE_CHAN_NOT_IMPLEMENTED
+/*@{ */
 
 #endif /* _ASTERISK_CAUSES_H */
diff --git a/include/asterisk/cdr.h b/include/asterisk/cdr.h
index b2307e5ba..96a5dc497 100644
--- a/include/asterisk/cdr.h
+++ b/include/asterisk/cdr.h
@@ -30,16 +30,21 @@
 #define AST_CDR_FLAG_CHILD			(1 << 3)
 #define AST_CDR_FLAG_POST_DISABLED		(1 << 4)
 
+/*! \name CDR Flags */
+/*@{ */
 #define AST_CDR_NULL                0
 #define AST_CDR_FAILED				(1 << 0)
 #define AST_CDR_BUSY				(1 << 1)
 #define AST_CDR_NOANSWER			(1 << 2)
 #define AST_CDR_ANSWERED			(1 << 3)
+/*@} */
 
-/*! AMA Flags */
+/*! \name CDR AMA Flags */
+/*@{ */
 #define AST_CDR_OMIT				(1)
 #define AST_CDR_BILLING				(2)
 #define AST_CDR_DOCUMENTATION			(3)
+/*@} */
 
 #define AST_MAX_USER_FIELD			256
 #define AST_MAX_ACCOUNT_CODE			20
@@ -48,7 +53,7 @@
 #include "asterisk/channel.h"
 #include "asterisk/utils.h"
 
-/*! Responsible for call detail data */
+/*! \brief Responsible for call detail data */
 struct ast_cdr {
 	/*! Caller*ID with text */
 	char clid[AST_MAX_EXTENSION];
@@ -298,11 +303,15 @@ char *ast_cdr_flags2str(int flags);
  */
 void ast_cdr_merge(struct ast_cdr *to, struct ast_cdr *from);
 
+/*! \brief Set account code, will generate AMI event */
 int ast_cdr_setaccount(struct ast_channel *chan, const char *account);
-int ast_cdr_setamaflags(struct ast_channel *chan, const char *amaflags);
 
+/*! \brief Set AMA flags for channel */
+int ast_cdr_setamaflags(struct ast_channel *chan, const char *amaflags);
 
+/*! \brief Set CDR user field for channel (stored in CDR) */
 int ast_cdr_setuserfield(struct ast_channel *chan, const char *userfield);
+/*! \brief Append to CDR user field for channel (stored in CDR) */
 int ast_cdr_appenduserfield(struct ast_channel *chan, const char *userfield);
 
 
@@ -316,10 +325,10 @@ extern char ast_default_accountcode[AST_MAX_ACCOUNT_CODE];
 
 struct ast_cdr *ast_cdr_append(struct ast_cdr *cdr, struct ast_cdr *newcdr);
 
-/*! Reload the configuration file cdr.conf and start/stop CDR scheduling thread */
+/*! \brief Reload the configuration file cdr.conf and start/stop CDR scheduling thread */
 int ast_cdr_engine_reload(void);
 
-/*! Load the configuration file cdr.conf and possibly start the CDR scheduling thread */
+/*! \brief Load the configuration file cdr.conf and possibly start the CDR scheduling thread */
 int ast_cdr_engine_init(void);
 
 /*! Submit any remaining CDRs and prepare for shutdown */
diff --git a/include/asterisk/devicestate.h b/include/asterisk/devicestate.h
index 68eedcfc8..d52430301 100644
--- a/include/asterisk/devicestate.h
+++ b/include/asterisk/devicestate.h
@@ -41,7 +41,7 @@
 extern "C" {
 #endif
 
-/*! Device States 
+/*! \brief Device States 
  *  \note The order of these states may not change because they are included
  *        in Asterisk events which may be transmitted across the network to
  *        other servers.
diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h
index d399eccbf..6e4b0e99b 100644
--- a/include/asterisk/doxyref.h
+++ b/include/asterisk/doxyref.h
@@ -350,7 +350,6 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \arg Implemented in \ref chan_h323.c
  * \section h323conf h323.conf
  * \ref chan_h323.c
- * \verbinclude h323.txt
  */
 
 /*! \page Config_oss OSS configuration
diff --git a/include/asterisk/dsp.h b/include/asterisk/dsp.h
index b34701f30..2664b9b3e 100644
--- a/include/asterisk/dsp.h
+++ b/include/asterisk/dsp.h
@@ -28,18 +28,18 @@
 #define DSP_FEATURE_DTMF_DETECT		(1 << 3)
 #define DSP_FEATURE_FAX_DETECT		(1 << 4)
 
-#define	DSP_DIGITMODE_DTMF			0				/* Detect DTMF digits */
-#define DSP_DIGITMODE_MF			1				/* Detect MF digits */
-
-#define DSP_DIGITMODE_NOQUELCH		(1 << 8)		/* Do not quelch DTMF from in-band */
-#define DSP_DIGITMODE_MUTECONF		(1 << 9)		/* Mute conference */
-#define DSP_DIGITMODE_MUTEMAX		(1 << 10)		/* Delay audio by a frame to try to extra quelch */
-#define DSP_DIGITMODE_RELAXDTMF		(1 << 11)		/* "Radio" mode (relaxed DTMF) */
-
-#define DSP_PROGRESS_TALK		(1 << 16)		/* Enable talk detection */
-#define DSP_PROGRESS_RINGING		(1 << 17)		/* Enable calling tone detection */
-#define DSP_PROGRESS_BUSY		(1 << 18)		/* Enable busy tone detection */
-#define DSP_PROGRESS_CONGESTION		(1 << 19)		/* Enable congestion tone detection */
+#define	DSP_DIGITMODE_DTMF			0				/*!< Detect DTMF digits */
+#define DSP_DIGITMODE_MF			1				/*!< Detect MF digits */
+
+#define DSP_DIGITMODE_NOQUELCH		(1 << 8)		/*!< Do not quelch DTMF from in-band */
+#define DSP_DIGITMODE_MUTECONF		(1 << 9)		/*!< Mute conference */
+#define DSP_DIGITMODE_MUTEMAX		(1 << 10)		/*!< Delay audio by a frame to try to extra quelch */
+#define DSP_DIGITMODE_RELAXDTMF		(1 << 11)		/*!< "Radio" mode (relaxed DTMF) */
+
+#define DSP_PROGRESS_TALK		(1 << 16)		/*!< Enable talk detection */
+#define DSP_PROGRESS_RINGING		(1 << 17)		/*!< Enable calling tone detection */
+#define DSP_PROGRESS_BUSY		(1 << 18)		/*!< Enable busy tone detection */
+#define DSP_PROGRESS_CONGESTION		(1 << 19)		/*!< Enable congestion tone detection */
 #define DSP_FEATURE_CALL_PROGRESS	(DSP_PROGRESS_TALK | DSP_PROGRESS_RINGING | DSP_PROGRESS_BUSY | DSP_PROGRESS_CONGESTION)
 
 #define DSP_TONE_STATE_SILENCE  0
diff --git a/include/asterisk/event.h b/include/asterisk/event.h
index 27d1f4a0a..6946b54e1 100644
--- a/include/asterisk/event.h
+++ b/include/asterisk/event.h
@@ -19,7 +19,8 @@
 /*!
  * \file
  * \author Russell Bryant <russell@digium.com>
- * \brief Generic event system
+ * \ref AstGenericEvents
+ * \page AstGenericEvents Generic event system
  *
  * The purpose of this API is to provide a generic way to share events between
  * Asterisk modules.  Code can generate events, and other code can subscribe to
diff --git a/include/asterisk/extconf.h b/include/asterisk/extconf.h
index f0e919575..943945031 100644
--- a/include/asterisk/extconf.h
+++ b/include/asterisk/extconf.h
@@ -15,6 +15,10 @@
  * the GNU General Public License Version 2. See the LICENSE file
  * at the top of the source tree.
  */
+/*! \file External configuration handlers (realtime and static configuration)
+ *  \author Steve Murphy <murf@digium.com>
+ *
+ */
 
 #ifndef _ASTERISK_EXTCONF_H
 #define _ASTERISK_EXTCONF_H
@@ -68,7 +72,7 @@ struct ast_config {
 
 /* ================== above: the config world; below, the dialplan world */
 
-/*! \brief ast_app: A registered application */
+/*! \brief A registered application */
 struct ast_app {
 	int (*execute)(struct ast_channel *chan, void *data);
 	const char *synopsis;			/*!< Synopsis text for 'show applications' */
@@ -78,7 +82,7 @@ struct ast_app {
 	char name[0];				/*!< Name of the application */
 };
 /*!
-   \brief ast_exten: An extension
+   \brief An extension
 	The dialplan is saved as a linked list with each context
 	having it's own linked list of extensions - one item per
 	priority.
@@ -108,7 +112,7 @@ struct ast_timing {
 	unsigned int dowmask;			/*!< Mask for day of week (mon-sun) */
 	unsigned int minmask[24];		/*!< Mask for minute */
 };
-/*! \brief ast_include: include= support in extensions.conf */
+/*! \brief include= support in extensions.conf */
 struct ast_include {
 	const char *name;
 	const char *rname;			/*!< Context to include */
@@ -119,7 +123,7 @@ struct ast_include {
 	char stuff[0];
 };
 
-/*! \brief ast_sw: Switch statement in extensions.conf */
+/*! \brief Switch statement in extensions.conf */
 struct ast_sw {
 	char *name;
 	const char *registrar;			/*!< Registrar */
@@ -130,14 +134,14 @@ struct ast_sw {
 	char stuff[0];
 };
 
-*! \brief ast_ignorepat: Ignore patterns in dial plan */
+*! \brief Ignore patterns in dial plan */
 struct ast_ignorepat {
 	const char *registrar;
 	struct ast_ignorepat *next;
 	const char pattern[0];
 };
 
-/*! \brief ast_context: An extension context */
+/*! \brief An extension context */
 struct ast_context {
 	ast_rwlock_t lock; 			/*!< A lock to prevent multiple threads from clobbering the context */
 	struct ast_exten *root;			/*!< The root of the list of extensions */
diff --git a/include/asterisk/hashtab.h b/include/asterisk/hashtab.h
index 0f8e1f9ad..ed9a95e84 100644
--- a/include/asterisk/hashtab.h
+++ b/include/asterisk/hashtab.h
@@ -21,8 +21,9 @@
 
 /*! \file
  * \brief Generic (perhaps overly so) hashtable implementation
-*/
-/*! \note
+ * \ref AstHash
+ */
+/*! \page AstHash Hash Table support in Asterisk
 
 A hash table is a structure that allows for an exact-match search
 in O(1) (or close to that) time.
@@ -39,6 +40,7 @@ The key for a value must be contained in the value, or we won't
 be able to find it in the bucket list.
 
 This implementation is pretty generic, because:
+
  1. The value and key are expected to be in a structure
     (along with other data, perhaps) and it's address is a "void *".
  2. The pointer to a compare function must be passed in at the
diff --git a/include/asterisk/io.h b/include/asterisk/io.h
index 6f227dc2c..ee22994a4 100644
--- a/include/asterisk/io.h
+++ b/include/asterisk/io.h
@@ -48,7 +48,7 @@ extern "C" {
 /*! Invalid fd */
 #define AST_IO_NVAL	POLLNVAL
 
-/*!
+/*! \brief
  * An Asterisk IO callback takes its id, a file descriptor, list of events, and
  * callback data as arguments and returns 0 if it should not be
  * run again, or non-zero if it should be run again.
diff --git a/include/asterisk/localtime.h b/include/asterisk/localtime.h
index 4d46198c7..25dd92e34 100644
--- a/include/asterisk/localtime.h
+++ b/include/asterisk/localtime.h
@@ -25,19 +25,19 @@
 #define _ASTERISK_LOCALTIME_H
 
 struct ast_tm {
-	int tm_sec;             /* Seconds. [0-60] (1 leap second) */
-	int tm_min;             /* Minutes. [0-59] */
-	int tm_hour;            /* Hours.   [0-23] */
-	int tm_mday;            /* Day.     [1-31] */
-	int tm_mon;             /* Month.   [0-11] */
-	int tm_year;            /* Year - 1900.  */
-	int tm_wday;            /* Day of week. [0-6] */
-	int tm_yday;            /* Days in year.[0-365]	*/
-	int tm_isdst;           /* DST.		[-1/0/1]*/
-	long int tm_gmtoff;     /* Seconds east of UTC.  */
-	char *tm_zone;          /* Timezone abbreviation.  */
+	int tm_sec;             /*!< Seconds. [0-60] (1 leap second) */
+	int tm_min;             /*!< Minutes. [0-59] */
+	int tm_hour;            /*!< Hours.   [0-23] */
+	int tm_mday;            /*!< Day.     [1-31] */
+	int tm_mon;             /*!< Month.   [0-11] */
+	int tm_year;            /*!< Year - 1900.  */
+	int tm_wday;            /*!< Day of week. [0-6] */
+	int tm_yday;            /*!< Days in year.[0-365]	*/
+	int tm_isdst;           /*!< DST.		[-1/0/1]*/
+	long int tm_gmtoff;     /*!< Seconds east of UTC.  */
+	char *tm_zone;          /*!< Timezone abbreviation.  */
 	/* NOTE: do NOT reorder this final item.  The order needs to remain compatible with struct tm */
-	int tm_usec;        /* microseconds */
+	int tm_usec;        /*!< microseconds */
 };
 
 struct ast_tm *ast_localtime(const struct timeval *timep, struct ast_tm *p_tm, const char *zone);
diff --git a/include/asterisk/logger.h b/include/asterisk/logger.h
index 8cc8d622a..cc4abb906 100644
--- a/include/asterisk/logger.h
+++ b/include/asterisk/logger.h
@@ -43,9 +43,8 @@ extern "C" {
 #define VERBOSE_PREFIX_3 "    -- "
 #define VERBOSE_PREFIX_4 "       > "
 
-/*! Used for sending a log message */
-/*!
-	\brief This is the standard logger function.  Probably the only way you will invoke it would be something like this:
+/*! \brief Used for sending a log message 
+	This is the standard logger function.  Probably the only way you will invoke it would be something like this:
 	ast_log(LOG_WHATEVER, "Problem with the %s Captain.  We should get some more.  Will %d be enough?\n", "flux capacitor", 10);
 	where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
 	on which log you wish to output to. These are implemented as macros, that
diff --git a/include/asterisk/mod_format.h b/include/asterisk/mod_format.h
index fad351335..c51bf681c 100644
--- a/include/asterisk/mod_format.h
+++ b/include/asterisk/mod_format.h
@@ -31,8 +31,9 @@
 extern "C" {
 #endif
 
-/*!
- * Each supported file format is described by the following fields.
+/*! \brief
+ * Each supported file format is described by the following structure.
+ *
  * Not all are necessary, the support routine implement default
  * values for some of them.
  * A handler typically fills a structure initializing the desired
@@ -91,7 +92,7 @@ struct ast_format {
 	struct ast_module *module;
 };
 
-/*!
+/*! \brief
  * This structure is allocated by file.c in one chunk,
  * together with buf_size and desc_size bytes of memory
  * to be used for private purposes (e.g. buffers etc.)