Doxygen improvements

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@31979 65c4cc65-6c06-0410-ace0-fbb531ad65f3

2 files changed, 187 insertions, 248 deletions

diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index a36949932..217918f6f 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -78,6 +78,7 @@
 	\par Reference
 	\arg channel.c - generic functions
  	\arg channel.h - declarations of functions, flags and structures
+	\arg translate.h - Transcoding support functions
 	\arg \ref channel_drivers - Implemented channel drivers
 	\arg \ref Def_Frame Asterisk Multimedia Frames
 
@@ -99,12 +100,11 @@
 extern "C" {
 #endif
 
-/*! Max length of an extension */
-#define AST_MAX_EXTENSION	80
-
-#define AST_MAX_CONTEXT		80
-
-#define AST_CHANNEL_NAME	80
+#define AST_MAX_EXTENSION	80	/*!< Max length of an extension */
+#define AST_MAX_CONTEXT		80	/*!< Max length of a context */
+#define AST_CHANNEL_NAME	80	/*!< Max length of an ast_channel name */
+#define MAX_LANGUAGE		20	/*!< Max length of the language setting */
+#define MAX_MUSICCLASS		20	/*!< Max length of the music class setting */
 
 #include "asterisk/compat.h"
 #include "asterisk/frame.h"
@@ -117,19 +117,16 @@ extern "C" {
 #include "asterisk/linkedlists.h"
 #include "asterisk/stringfields.h"
 
-#define MAX_LANGUAGE		20
-
-#define MAX_MUSICCLASS		20
 
 #define AST_MAX_FDS		8
 /*
  * We have AST_MAX_FDS file descriptors in a channel.
  * Some of them have a fixed use:
  */
-#define AST_ALERT_FD	(AST_MAX_FDS-1)		/* used for alertpipe */
-#define AST_TIMING_FD	(AST_MAX_FDS-2)		/* used for timingfd */
-#define AST_AGENT_FD	(AST_MAX_FDS-3) /* used by agents for pass thru */
-#define AST_GENERATOR_FD	(AST_MAX_FDS-4) /* used by generator */
+#define AST_ALERT_FD	(AST_MAX_FDS-1)		/*!< used for alertpipe */
+#define AST_TIMING_FD	(AST_MAX_FDS-2)		/*!< used for timingfd */
+#define AST_AGENT_FD	(AST_MAX_FDS-3)		/*!< used by agents for pass through */
+#define AST_GENERATOR_FD	(AST_MAX_FDS-4)	/*!< used by generator */
 
 enum ast_bridge_result {
 	AST_BRIDGE_COMPLETE = 0,
@@ -146,43 +143,40 @@ struct ast_generator {
 	int (*generate)(struct ast_channel *chan, void *data, int len, int samples);
 };
 
-/*! Structure for a data store type */
+/*! \brief Structure for a data store type */
 struct ast_datastore_info {
-	const char *type;		/*! Type of data store */
-	void (*destroy)(void *data);	/*! Destroy function */
+	const char *type;		/*!< Type of data store */
+	void (*destroy)(void *data);	/*!< Destroy function */
 };
 
-/*! Structure for a channel data store */
+/*! \brief Structure for a channel data store */
 struct ast_datastore {
-	/*! Unique data store identifier */
-	char *uid;
-	/*! Contained data */
-	void *data;
-	/*! Data store type information */
-	const struct ast_datastore_info *info;
-	/*! Used for easy linking */
-	AST_LIST_ENTRY(ast_datastore) entry;
+	char *uid;		/*!< Unique data store identifier */
+	void *data;		/*!< Contained data */
+	const struct ast_datastore_info *info;	/*!< Data store type information */
+	AST_LIST_ENTRY(ast_datastore) entry; /*!< Used for easy linking */
 };
 
-/*! Structure for all kinds of caller ID identifications.
- * All string fields here are malloc'ed, so they need to be
+/*! \brief Structure for all kinds of caller ID identifications.
+ * \note All string fields here are malloc'ed, so they need to be
  * freed when the structure is deleted.
  * Also, NULL and "" must be considered equivalent.
  */
 struct ast_callerid {
-	char *cid_dnid;		/*! Malloc'd Dialed Number Identifier */
-	char *cid_num;		/*! Malloc'd Caller Number */
-	char *cid_name;		/*! Malloc'd Caller Name */
-	char *cid_ani;		/*! Malloc'd ANI */
-	char *cid_rdnis;	/*! Malloc'd RDNIS */
-	int cid_pres;		/*! Callerid presentation/screening */
-	int cid_ani2;		/*! Callerid ANI 2 (Info digits) */
-	int cid_ton;		/*! Callerid Type of Number */
-	int cid_tns;		/*! Callerid Transit Network Select */
+	char *cid_dnid;		/*!< Malloc'd Dialed Number Identifier */
+	char *cid_num;		/*!< Malloc'd Caller Number */
+	char *cid_name;		/*!< Malloc'd Caller Name */
+	char *cid_ani;		/*!< Malloc'd ANI */
+	char *cid_rdnis;	/*!< Malloc'd RDNIS */
+	int cid_pres;		/*!< Callerid presentation/screening */
+	int cid_ani2;		/*!< Callerid ANI 2 (Info digits) */
+	int cid_ton;		/*!< Callerid Type of Number */
+	int cid_tns;		/*!< Callerid Transit Network Select */
 };
 
-/*! Structure to describe a channel "technology", ie a channel driver 
-	See
+/*! \brief 
+	Structure to describe a channel "technology", ie a channel driver 
+	See for examples:
 	\arg chan_iax2.c - The Inter-Asterisk exchange protocol
 	\arg chan_sip.c - The SIP channel driver
 	\arg chan_zap.c - PSTN connectivity (TDM, PRI, T1/E1, FXO, FXS)
@@ -192,215 +186,174 @@ struct ast_callerid {
 	this driver supports and where different callbacks are 
 	implemented.
 */
-	
-
 struct ast_channel_tech {
 	const char * const type;
 	const char * const description;
 
-	/*! Bitmap of formats this channel can handle */
-	int capabilities;
+	int capabilities;		/*!< Bitmap of formats this channel can handle */
 
-	/*! Technology Properties */
-	int properties;
+	int properties;			/*!< Technology Properties */
 
-	/*! Requester - to set up call data structures (pvt's) */
+	/*! \brief Requester - to set up call data structures (pvt's) */
 	struct ast_channel *(* const requester)(const char *type, int format, void *data, int *cause);
 
-	/*! Devicestate call back */
-	int (* const devicestate)(void *data);
+	int (* const devicestate)(void *data);	/*!< Devicestate call back */
 
-	/*! Send a literal DTMF digit */
-	int (* const send_digit)(struct ast_channel *chan, char digit);
+	int (* const send_digit)(struct ast_channel *chan, char digit);	/*!< Send a literal DTMF digit */
 
-	/*! Start sending a literal DTMF digit */
+	/*! \brief Start sending a literal DTMF digit */
 	int (* const send_digit_begin)(struct ast_channel *chan, char digit);
 
-	/*! Stop sending the last literal DTMF digit */
+	/*! \brief Stop sending the last literal DTMF digit */
 	int (* const send_digit_end)(struct ast_channel *chan);
 
-	/*! Call a given phone number (address, etc), but don't
+	/*! \brief Call a given phone number (address, etc), but don't
 	   take longer than timeout seconds to do so.  */
 	int (* const call)(struct ast_channel *chan, char *addr, int timeout);
 
-	/*! Hangup (and possibly destroy) the channel */
+	/*! \brief Hangup (and possibly destroy) the channel */
 	int (* const hangup)(struct ast_channel *chan);
 
-	/*! Answer the channel */
+	/*! \brief Answer the channel */
 	int (* const answer)(struct ast_channel *chan);
 
-	/*! Read a frame, in standard format (see frame.h) */
+	/*! \brief Read a frame, in standard format (see frame.h) */
 	struct ast_frame * (* const read)(struct ast_channel *chan);
 
-	/*! Write a frame, in standard format (see frame.h) */
+	/*! \brief Write a frame, in standard format (see frame.h) */
 	int (* const write)(struct ast_channel *chan, struct ast_frame *frame);
 
-	/*! Display or transmit text */
+	/*! \brief Display or transmit text */
 	int (* const send_text)(struct ast_channel *chan, const char *text);
 
-	/*! Display or send an image */
+	/*! \brief Display or send an image */
 	int (* const send_image)(struct ast_channel *chan, struct ast_frame *frame);
 
-	/*! Send HTML data */
+	/*! \brief Send HTML data */
 	int (* const send_html)(struct ast_channel *chan, int subclass, const char *data, int len);
 
-	/*! Handle an exception, reading a frame */
+	/*! \brief Handle an exception, reading a frame */
 	struct ast_frame * (* const exception)(struct ast_channel *chan);
 
-	/*! Bridge two channels of the same type together */
+	/*! \brief Bridge two channels of the same type together */
 	enum ast_bridge_result (* const bridge)(struct ast_channel *c0, struct ast_channel *c1, int flags,
 						struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
 
-	/*! Indicate a particular condition (e.g. AST_CONTROL_BUSY or AST_CONTROL_RINGING or AST_CONTROL_CONGESTION */
+	/*! \brief Indicate a particular condition (e.g. AST_CONTROL_BUSY or AST_CONTROL_RINGING or AST_CONTROL_CONGESTION */
 	int (* const indicate)(struct ast_channel *c, int condition, const void *data, size_t datalen);
 
-	/*! Fix up a channel:  If a channel is consumed, this is called.  Basically update any ->owner links */
+	/*! \brief Fix up a channel:  If a channel is consumed, this is called.  Basically update any ->owner links */
 	int (* const fixup)(struct ast_channel *oldchan, struct ast_channel *newchan);
 
-	/*! Set a given option */
+	/*! \brief Set a given option */
 	int (* const setoption)(struct ast_channel *chan, int option, void *data, int datalen);
 
-	/*! Query a given option */
+	/*! \brief Query a given option */
 	int (* const queryoption)(struct ast_channel *chan, int option, void *data, int *datalen);
 
-	/*! Blind transfer other side (see app_transfer.c and ast_transfer() */
+	/*! \brief Blind transfer other side (see app_transfer.c and ast_transfer() */
 	int (* const transfer)(struct ast_channel *chan, const char *newdest);
 
-	/*! Write a frame, in standard format */
+	/*! \brief Write a frame, in standard format */
 	int (* const write_video)(struct ast_channel *chan, struct ast_frame *frame);
 
-	/*! Find bridged channel */
+	/*! \brief Find bridged channel */
 	struct ast_channel *(* const bridged_channel)(struct ast_channel *chan, struct ast_channel *bridge);
 
-	/*! Provide additional items for CHANNEL() dialplan function */
+	/*! \brief Provide additional read items for CHANNEL() dialplan function */
 	int (* func_channel_read)(struct ast_channel *chan, char *function, char *data, char *buf, size_t len);
+
+	/*! \brief Provide additional write items for CHANNEL() dialplan function */
 	int (* func_channel_write)(struct ast_channel *chan, char *function, char *data, const char *value);
 };
 
 struct ast_channel_spy_list;
 
-/*! Main Channel structure associated with a channel. 
+#define	DEBUGCHAN_FLAG  0x80000000
+#define	FRAMECOUNT_INC(x)	( ((x) & DEBUGCHAN_FLAG) | ((x++) & ~DEBUGCHAN_FLAG) )
+
+
+/*! \brief Main Channel structure associated with a channel. 
  * This is the side of it mostly used by the pbx and call management.
  *
  * \note XXX It is important to remember to increment .cleancount each time
  *       this structure is changed. XXX
  */
 struct ast_channel {
-	/*! Technology (point to channel driver) */
+	/*! \brief Technology (point to channel driver) */
 	const struct ast_channel_tech *tech;
 
-	/*! Private data used by the technology driver */
+	/*! \brief Private data used by the technology driver */
 	void *tech_pvt;
 
 	AST_DECLARE_STRING_FIELDS(
-		AST_STRING_FIELD(name);			/*! ASCII unique channel name */
-		AST_STRING_FIELD(language);		/*! Language requested for voice prompts */
-		AST_STRING_FIELD(musicclass);		/*! Default music class */
-		AST_STRING_FIELD(accountcode);		/*! Account code for billing */
-		AST_STRING_FIELD(call_forward);		/*! Where to forward to if asked to dial on this interface */
-		AST_STRING_FIELD(uniqueid);		/*! Unique Channel Identifier */
+		AST_STRING_FIELD(name);			/*!< ASCII unique channel name */
+		AST_STRING_FIELD(language);		/*!< Language requested for voice prompts */
+		AST_STRING_FIELD(musicclass);		/*!< Default music class */
+		AST_STRING_FIELD(accountcode);		/*!< Account code for billing */
+		AST_STRING_FIELD(call_forward);		/*!< Where to forward to if asked to dial on this interface */
+		AST_STRING_FIELD(uniqueid);		/*!< Unique Channel Identifier */
 	);
 	
-	/*! File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1.  */
+	/*! \brief File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1.  */
 	int fds[AST_MAX_FDS];			
 
-	/*! Music State*/
-	void *music_state;
-	/*! Current generator data if there is any */
-	void *generatordata;
-	/*! Current active data generator */
-	struct ast_generator *generator;
+	void *music_state;				/*!< Music State*/
+	void *generatordata;				/*!< Current generator data if there is any */
+	struct ast_generator *generator;		/*!< Current active data generator */
 
-	/*! Who are we bridged to, if we're bridged. Who is proxying for us,
+	/*! \brief Who are we bridged to, if we're bridged. Who is proxying for us,
 	  if we are proxied (i.e. chan_agent).
 	  Do not access directly, use ast_bridged_channel(chan) */
 	struct ast_channel *_bridge;
-	/*! Channel that will masquerade as us */
-	struct ast_channel *masq;		
-	/*! Who we are masquerading as */
-	struct ast_channel *masqr;		
-	/*! Call Detail Record Flags */
-	int cdrflags;										   
-	/*! Whether or not we have been hung up...  Do not set this value
+	struct ast_channel *masq;			/*!< Channel that will masquerade as us */
+	struct ast_channel *masqr;			/*!< Who we are masquerading as */
+	int cdrflags;					/*!< Call Detail Record Flags */
+
+	/*! \brief Whether or not we have been hung up...  Do not set this value
 	    directly, use ast_softhangup */
 	int _softhangup;
-	/*! Non-zero, set to actual time when channel is to be hung up */
-	time_t	whentohangup;
-	/*! If anyone is blocking, this is them */
-	pthread_t blocker;			
-	/*! Lock, can be used to lock a channel for some operations */
-	ast_mutex_t lock;			
-	/*! Procedure causing blocking */
-	const char *blockproc;			
-
-	const char *appl;				/*! Current application */
-	const char *data;				/*! Data passed to current application */
-	
-	/*! Which fd had an event detected on */
-	int fdno;				
-	/*! Schedule context */
-	struct sched_context *sched;		
-	/*! For streaming playback, the schedule ID */
-	int streamid;				
-	/*! Stream itself. */
-	struct ast_filestream *stream;		
-	/*! For streaming video playback, the schedule ID */
-	int vstreamid;				
-	/*! Video Stream itself. */
-	struct ast_filestream *vstream;		
-	/*! Original writer format */
-	int oldwriteformat;			
+	time_t	whentohangup;				/*!< Non-zero, set to actual time when channel is to be hung up */
+	pthread_t blocker;				/*!< If anyone is blocking, this is them */
+	ast_mutex_t lock;				/*!< Lock, can be used to lock a channel for some operations */
+	const char *blockproc;				/*!< Procedure causing blocking */
+
+	const char *appl;				/*!< Current application */
+	const char *data;				/*!< Data passed to current application */
+	int fdno;					/*!< Which fd had an event detected on */
+	struct sched_context *sched;			/*!< Schedule context */
+	int streamid;					/*!< For streaming playback, the schedule ID */
+	struct ast_filestream *stream;			/*!< Stream itself. */
+	int vstreamid;					/*!< For streaming video playback, the schedule ID */
+	struct ast_filestream *vstream;			/*!< Video Stream itself. */
+	int oldwriteformat;				/*!< Original writer format */
 	
-	/*! Timing fd */
-	int timingfd;
+	int timingfd;					/*!< Timing fd */
 	int (*timingfunc)(void *data);
 	void *timingdata;
 
-	/*! State of line -- Don't write directly, use ast_setstate */
-	int _state;				
-	/*! Number of rings so far */
-	int rings;				
-
-	/*! Kinds of data this channel can natively handle */
-	int nativeformats;			
-	/*! Requested read format */
-	int readformat;				
-	/*! Requested write format */
-	int writeformat;			
-
-	struct ast_callerid cid;
-		
-	/*! Current extension context */
-	char context[AST_MAX_CONTEXT];
-	/*! Current non-macro context */
-	char macrocontext[AST_MAX_CONTEXT];	
-	/*! Current non-macro extension */
-	char macroexten[AST_MAX_EXTENSION];
-	/*! Current non-macro priority */
-	int macropriority;
-	/*! Current extension number */
-	char exten[AST_MAX_EXTENSION];		
-	/* Current extension priority */
-	int priority;						
-	/*! Any/all queued DTMF characters */
-	char dtmfq[AST_MAX_EXTENSION];		
-	/*! DTMF frame */
-	struct ast_frame dtmff;			
-
-	/*! PBX private structure */
-	struct ast_pbx *pbx;
-	/*! Set BEFORE PBX is started to determine AMA flags */
-	int amaflags;			
-	/*! Call Detail Record */
-	struct ast_cdr *cdr;			
-	/*! Whether or not ADSI is detected on CPE */
-	int adsicpe;
-
-	/*! Tone zone as set in indications.conf */
-	struct tone_zone *zone;
-
-	/* Channel monitoring */
-	struct ast_channel_monitor *monitor;
+	int _state;					/*!< State of line -- Don't write directly, use ast_setstate */
+	int rings;					/*!< Number of rings so far */
+	struct ast_callerid cid;			/*!< Caller ID, name, presentation etc */
+	char dtmfq[AST_MAX_EXTENSION];			/*!< Any/all queued DTMF characters */
+	struct ast_frame dtmff;				/*!< DTMF frame */
+
+	char context[AST_MAX_CONTEXT];			/*!< Dialplan: Current extension context */
+	char exten[AST_MAX_EXTENSION];			/*!< Dialplan: Current extension number */
+	int priority;					/*!< Dialplan: Current extension priority */
+	char macrocontext[AST_MAX_CONTEXT];		/*!< Macro: Current non-macro context. See app_macro.c */
+	char macroexten[AST_MAX_EXTENSION];		/*!< Macro: Current non-macro extension. See app_macro.c */
+	int macropriority;				/*!< Macro: Current non-macro priority. See app_macro.c */
+
+	struct ast_pbx *pbx;				/*!< PBX private structure for this channel */
+	int amaflags;					/*!< Set BEFORE PBX is started to determine AMA flags */
+	struct ast_cdr *cdr;				/*!< Call Detail Record */
+	int adsicpe;					/*!< Whether or not ADSI is detected on CPE */
+
+	struct tone_zone *zone;				/*!< Tone zone as set in indications.conf or
+								in the CHANNEL dialplan function */
+
+	struct ast_channel_monitor *monitor;		/*!< Channel monitoring */
 
 	/*! Track the read/written samples for monitor use */
 	unsigned long insmpl;
@@ -411,56 +364,37 @@ struct ast_channel {
 	 */
 	unsigned int fin;
 	unsigned int fout;
-#define	DEBUGCHAN_FLAG  0x80000000
-#define	FRAMECOUNT_INC(x)	( ((x) & DEBUGCHAN_FLAG) | ((x++) & ~DEBUGCHAN_FLAG) )
-
-	/* Why is the channel hanged up */
-	int hangupcause;
-	
-	/* A linked list for variables */
-	struct varshead varshead;
-
-	unsigned int callgroup;
-	unsigned int pickupgroup;
-
-	/*! channel flags of AST_FLAG_ type */
-	unsigned int flags;
-	
-	/*! ISDN Transfer Capbility - AST_FLAG_DIGITAL is not enough */
-	unsigned short transfercapability;
-
+	int hangupcause;				/*!< Why is the channel hanged up. See causes.h */
+	struct varshead varshead;			/*!< A linked list for channel variables */
+	unsigned int callgroup;				/*!< Call group for call pickups */
+	unsigned int pickupgroup;			/*!< Pickup group - which calls groups can be picked up? */
+	unsigned int flags;				/*!< channel flags of AST_FLAG_ type */
+	unsigned short transfercapability;		/*!< ISDN Transfer Capbility - AST_FLAG_DIGITAL is not enough */
 	struct ast_frame *readq;
 	int alertpipe[2];
-	/*! Write translation path */
-	struct ast_trans_pvt *writetrans;
-	/*! Read translation path */
-	struct ast_trans_pvt *readtrans;
-	/*! Raw read format */
-	int rawreadformat;
-	/*! Raw write format */
-	int rawwriteformat;
-
-	/*! Chan Spy stuff */
-	struct ast_channel_spy_list *spies;
-
-	/*! Data stores on the channel */
-	AST_LIST_HEAD_NOLOCK(datastores, ast_datastore) datastores;
 
-	/*! For easy linking */
-	AST_LIST_ENTRY(ast_channel) chan_list;
+	int nativeformats;				/*!< Kinds of data this channel can natively handle */
+	int readformat;					/*!< Requested read format */
+	int writeformat;				/*!< Requested write format */
+	struct ast_trans_pvt *writetrans;		/*!< Write translation path */
+	struct ast_trans_pvt *readtrans;		/*!< Read translation path */
+	int rawreadformat;				/*!< Raw read format */
+	int rawwriteformat;				/*!< Raw write format */
+
+	struct ast_channel_spy_list *spies;		/*!< Chan Spy stuff */
+	AST_LIST_ENTRY(ast_channel) chan_list;		/*!< For easy linking */
+	struct ast_jb jb;				/*!< The jitterbuffer state  */
 
-	/*! The jitterbuffer state  */
-	struct ast_jb jb;
+	/*! \brief Data stores on the channel */
+	AST_LIST_HEAD_NOLOCK(datastores, ast_datastore) datastores;
 };
 
-/* \defgroup chanprop Channel tech properties:
+/*! \defgroup chanprop Channel tech properties:
 	\brief Channels have this property if they can accept input with jitter; i.e. most VoIP channels */
-/* @{ */
+/*! @{ */
 #define AST_CHAN_TP_WANTSJITTER	(1 << 0)	
 
-/* \defgroup chanprop Channel tech properties:
-	\brief Channels have this property if they can create jitter; i.e. most VoIP channels */
-/* @{ */
+/*! \brief Channels have this property if they can create jitter; i.e. most VoIP channels */
 #define AST_CHAN_TP_CREATESJITTER (1 << 1)
 
 /* This flag has been deprecated by the transfercapbilty data member in struct ast_channel */
@@ -656,7 +590,7 @@ void  ast_channel_free(struct ast_channel *);
 
 /*! \brief Requests a channel 
  * \param type type of channel to request
- * \param format requested channel format
+ * \param format requested channel format (codec)
  * \param data data to pass to the channel requester
  * \param status status
  * Request a channel of a given type, with data as optional information used 
@@ -1225,8 +1159,8 @@ int ast_internal_timing_enabled(struct ast_channel *chan);
 
 /* Misc. functions below */
 
-/* if fd is a valid descriptor, set *pfd with the descriptor
- * Return 1 (not -1!) if added, 0 otherwise (so we can add the
+/*! \brief if fd is a valid descriptor, set *pfd with the descriptor
+ * \return Return 1 (not -1!) if added, 0 otherwise (so we can add the
  * return value to the index into the array)
  */
 static inline int ast_add_fd(struct pollfd *pfd, int fd)
@@ -1236,7 +1170,7 @@ static inline int ast_add_fd(struct pollfd *pfd, int fd)
 	return fd >= 0;
 }
 
-/* Helper function for migrating select to poll */
+/*! \brief Helper function for migrating select to poll */
 static inline int ast_fdisset(struct pollfd *pfds, int fd, int max, int *start)
 {
 	int x;
diff --git a/include/asterisk/translate.h b/include/asterisk/translate.h
index d1431b3be..182330ace 100644
--- a/include/asterisk/translate.h
+++ b/include/asterisk/translate.h
@@ -38,14 +38,15 @@ extern "C" {
 
 struct ast_trans_pvt;	/* declared below */
 
-/*!
+/*! \brief
  * Descriptor of a translator. Name, callbacks, and various options
  * related to run-time operation (size of buffers, auxiliary
  * descriptors, etc).
+ *
  * A coded registers itself by filling the relevant fields
  * of a structure and passing it as an argument to
  * ast_register_translator(). The structure should not be
- * modified after a successful register(), and its address
+ * modified after a successful registration, and its address
  * must be used as an argument to ast_unregister_translator().
  *
  * As a minimum, a translator should supply name, srcfmt and dstfmt,
@@ -64,49 +65,52 @@ struct ast_trans_pvt;	/* declared below */
  * Generic plc is only available for dstfmt = SLINEAR
  */
 struct ast_translator {
-	const char name[80];		/*! Name of translator */
-	int srcfmt;			/*! Source format (note: bit position,
+	const char name[80];		/*!< Name of translator */
+	int srcfmt;			/*!< Source format (note: bit position,
 					  converted to index during registration) */
-	int dstfmt;			/*! Destination format (note: bit position,
+	int dstfmt;			/*!< Destination format (note: bit position,
 					  converted to index during registration) */
 
-	/*! initialize private data associated with the translator */
-	void *(*newpvt)(struct ast_trans_pvt *);
+	void *(*newpvt)(struct ast_trans_pvt *); /*!< initialize private data 
+					associated with the translator */
 
-	/*! Input frame callback. Store (and possibly convert) input frame. */
 	int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
+					/*!< Input frame callback. Store 
+					     (and possibly convert) input frame. */
 
-	/*! Output frame callback. Generate a frame with outbuf content. */
 	struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
+					/*!< Output frame callback. Generate a frame 
+					    with outbuf content. */
 
-	/*! cleanup private data, if needed (often unnecessary). */
 	void (*destroy)(struct ast_trans_pvt *pvt);
+					/*!< cleanup private data, if needed 
+						(often unnecessary). */
 
-	struct ast_frame * (*sample)(void);	/*! Generate an example frame */
+	struct ast_frame * (*sample)(void);	/*!< Generate an example frame */
 
-	/*! size of outbuf, in samples. Leave it 0 if you want the framein
+	/*! \brief size of outbuf, in samples. Leave it 0 if you want the framein
 	 * callback deal with the frame. Set it appropriately if you
 	 * want the code to checks if the incoming frame fits the
 	 * outbuf (this is e.g. required for plc).
 	 */
-	int buffer_samples;	/* size of outbuf, in samples */
+	int buffer_samples;	/*< size of outbuf, in samples */
 
-	/*! size of outbuf, in bytes. Mandatory. The wrapper code will also
+	/*! \brief size of outbuf, in bytes. Mandatory. The wrapper code will also
 	 * allocate an AST_FRIENDLY_OFFSET space before.
 	 */
 	int buf_size;
 
-	int desc_size;		/*! size of private descriptor in pvt->pvt, if any */
-	int plc_samples;	/* set to the plc block size if used, 0 otherwise */
-	int useplc;		/* current status of plc, changed at runtime */
+	int desc_size;		/*!< size of private descriptor in pvt->pvt, if any */
+	int plc_samples;	/*!< set to the plc block size if used, 0 otherwise */
+	int useplc;		/*!< current status of plc, changed at runtime */
 
-	void *module;		/* opaque reference to the parent module */
+	void *module;		/*!< opaque reference to the parent module */
 
-	int cost;		/*! Cost in milliseconds for encoding/decoding 1 second of sound */
-	AST_LIST_ENTRY(ast_translator) list;	/*! link field */
+	int cost;		/*!< Cost in milliseconds for encoding/decoding 1 second of sound */
+	AST_LIST_ENTRY(ast_translator) list;	/*!< link field */
 };
 
-/*
+/*! \brief
  * Default structure for translators, with the basic fields and buffers,
  * all allocated as part of the same chunk of memory. The buffer is
  * preceded by AST_FRIENDLY_OFFSET bytes in front of the user portion.
@@ -126,18 +130,18 @@ struct ast_translator {
  */
 struct ast_trans_pvt {
 	struct ast_translator *t;
-	struct ast_frame f;	/* used in frameout */
-	int samples;		/* samples available in outbuf */
-	int datalen;		/* actual space used in outbuf */
-	void *pvt;		/* more private data, if any */
-	char *outbuf;		/* the useful portion of the buffer */
-	plc_state_t *plc;	/* optional plc pointer */
-	struct ast_trans_pvt *next;	/* next in translator chain */
+	struct ast_frame f;	/*!< used in frameout */
+	int samples;		/*!< samples available in outbuf */
+	int datalen;		/*!< actual space used in outbuf */
+	void *pvt;		/*!< more private data, if any */
+	char *outbuf;		/*!< the useful portion of the buffer */
+	plc_state_t *plc;	/*!< optional plc pointer */
+	struct ast_trans_pvt *next;	/*!< next in translator chain */
 	struct timeval nextin;
 	struct timeval nextout;
 };
 
-/* generic frameout function */
+/*! \brief generic frameout function */
 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
         int datalen, int samples);
 
@@ -145,17 +149,17 @@ struct ast_trans_pvt;
 
 /*!
  * \brief Register a translator
+ * This registers a codec translator with asterisk
  * \param t populated ast_translator structure
  * \param module handle to the module that owns this translator
- * This registers a codec translator with asterisk
  * \return 0 on success, -1 on failure
  */
 int ast_register_translator(struct ast_translator *t, void *module);
 
 /*!
  * \brief Unregister a translator
- * \param t translator to unregister
  * Unregisters the given tranlator
+ * \param t translator to unregister
  * \return 0 on success, -1 on failure
  */
 int ast_unregister_translator(struct ast_translator *t);
@@ -164,34 +168,35 @@ int ast_unregister_translator(struct ast_translator *t);
  * \brief Chooses the best translation path
  *
  * Given a list of sources, and a designed destination format, which should
- * I choose? Returns 0 on success, -1 if no path could be found.  Modifies
- * dests and srcs in place 
+ * I choose? 
+ * \return Returns 0 on success, -1 if no path could be found.  
+ * \note Modifies dests and srcs in place 
  */
 int ast_translator_best_choice(int *dsts, int *srcs);
 
 /*! 
  * \brief Builds a translator path
+ * Build a path (possibly NULL) from source to dest 
  * \param dest destination format
  * \param source source format
- * Build a path (possibly NULL) from source to dest 
  * \return ast_trans_pvt on success, NULL on failure
  * */
 struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
 
 /*!
  * \brief Frees a translator path
- * \param tr translator path to get rid of
  * Frees the given translator path structure
+ * \param tr translator path to get rid of
  */
 void ast_translator_free_path(struct ast_trans_pvt *tr);
 
 /*!
  * \brief translates one or more frames
+ * Apply an input frame into the translator and receive zero or one output frames.  Consume
+ * determines whether the original frame should be freed
  * \param tr translator structure to use for translation
  * \param f frame to translate
  * \param consume Whether or not to free the original frame
- * Apply an input frame into the translator and receive zero or one output frames.  Consume
- * determines whether the original frame should be freed
  * \return an ast_frame of the new translation format on success, NULL on failure
  */
 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);