Doxygen improvements
authorOlle Johansson <oej@edvina.net>
Sun, 4 Jun 2006 08:57:34 +0000 (08:57 +0000)
committerOlle Johansson <oej@edvina.net>
Sun, 4 Jun 2006 08:57:34 +0000 (08:57 +0000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@31979 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/channel.h
include/asterisk/translate.h

index a369499..217918f 100644 (file)
@@ -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
 
 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;
index d1431b3..182330a 100644 (file)
@@ -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);