Convert most of the existing comments in kernel.h to doxygen format

git-svn-id: http://svn.asterisk.org/svn/dahdi/linux/trunk@4658 a0bf4364-ded3-4de4-8d8a-66a801d63aff

1 files changed, 229 insertions, 223 deletions

diff --git a/include/dahdi/kernel.h b/include/dahdi/kernel.h
index cbfadd0..cae305b 100644
--- a/include/dahdi/kernel.h
+++ b/include/dahdi/kernel.h
@@ -24,6 +24,11 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 
  */
 
+/*!
+ * \file
+ * \brief DAHDI kernel interface definitions
+ */
+
 #ifndef _DAHDI_KERNEL_H
 #define _DAHDI_KERNEL_H
 
@@ -72,7 +77,7 @@
 #define DAHDI_IRQ_SHARED_DISABLED SA_SHIRQ | SA_INTERRUPT
 #endif
 
-/* Default chunk size for conferences and such -- static right now, might make
+/*! Default chunk size for conferences and such -- static right now, might make
    variable sometime.  8 samples = 1 ms = most frequent service interval possible
    for a USB device */
 #define DAHDI_CHUNKSIZE		 8
@@ -81,7 +86,7 @@
 #define DAHDI_MAX_CHUNKSIZE 	 DAHDI_CHUNKSIZE
 #define DAHDI_CB_SIZE		 2
 
-#define RING_DEBOUNCE_TIME	2000	/* 2000 ms ring debounce time */
+#define RING_DEBOUNCE_TIME	2000	/*!< 2000 ms ring debounce time */
 
 #include "ecdis.h"
 
@@ -107,7 +112,7 @@ struct dahdi_tone_state {
 	int modulate;
 };
 
-/* Conference queue stucture */
+/*! \brief Conference queue structure */
 struct confq {
 	u_char buffer[DAHDI_CHUNKSIZE * DAHDI_CB_SIZE];
 	u_char *buf[DAHDI_CB_SIZE];
@@ -117,7 +122,7 @@ struct confq {
 
 struct dahdi_chan {
 #ifdef CONFIG_DAHDI_NET
-	/* Must be first */
+	/*! \note Must be first */
 	struct dahdi_hdlc *hdlcnetdev;
 #endif
 #ifdef CONFIG_DAHDI_PPP
@@ -128,9 +133,10 @@ struct dahdi_chan {
 	struct sk_buff_head ppp_rq;
 #endif
 	spinlock_t lock;
-	char name[40];		/* Name */
+	char name[40];
 	/* Specified by DAHDI */
-	int channo;			/* DAHDI Channel number */
+	/*! \brief DAHDI channel number */
+	int channo;
 	int chanpos;
 	unsigned long flags;
 	long rxp1;
@@ -145,90 +151,90 @@ struct dahdi_chan {
 	int toneflags;
 	sf_detect_state_t rd;
 
-	struct dahdi_chan *master;	/* Our Master channel (could be us) */
-	/* Next slave (if appropriate) */
+	struct dahdi_chan *master;	/*!< Our Master channel (could be us) */
+	/*! \brief Next slave (if appropriate) */
 	int nextslave;
 
-	u_char *writechunk;						/* Actual place to write to */
-	u_char swritechunk[DAHDI_MAX_CHUNKSIZE];	/* Buffer to be written */
-	u_char *readchunk;						/* Actual place to read from */
-	u_char sreadchunk[DAHDI_MAX_CHUNKSIZE];	/* Preallocated static area */
+	u_char *writechunk;						/*!< Actual place to write to */
+	u_char swritechunk[DAHDI_MAX_CHUNKSIZE];	/*!< Buffer to be written */
+	u_char *readchunk;						/*!< Actual place to read from */
+	u_char sreadchunk[DAHDI_MAX_CHUNKSIZE];	/*!< Preallocated static area */
 	short *readchunkpreec;
 
-	/* Pointer to tx and rx gain tables */
+	/*! Pointer to tx and rx gain tables */
 	u_char *rxgain;
 	u_char *txgain;
 	
-	/* Whether or not we have allocated gains or are using the default */
+	/*! Whether or not we have allocated gains or are using the default */
 	int gainalloc;
 
 	/* Specified by driver, readable by DAHDI */
-	void *pvt;			/* Private channel data */
-	struct file *file;	/* File structure */
+	void *pvt;			/*!< Private channel data */
+	struct file *file;	/*!< File structure */
 	
 	
-	struct dahdi_span	*span;			/* Span we're a member of */
-	int		sig;			/* Signalling */
-	int		sigcap;			/* Capability for signalling */
-	__u32		chan_alarms;		/* alarms status */
+	struct dahdi_span	*span;			/*!< Span we're a member of */
+	int		sig;			/*!< Signalling */
+	int		sigcap;			/*!< Capability for signalling */
+	__u32		chan_alarms;		/*!< alarms status */
 
 	/* Used only by DAHDI -- NO DRIVER SERVICEABLE PARTS BELOW */
 	/* Buffer declarations */
-	u_char		*readbuf[DAHDI_MAX_NUM_BUFS];	/* read buffer */
+	u_char		*readbuf[DAHDI_MAX_NUM_BUFS];	/*!< read buffer */
 	int		inreadbuf;
 	int		outreadbuf;
-	wait_queue_head_t readbufq; /* read wait queue */
+	wait_queue_head_t readbufq; /*!< read wait queue */
 
-	u_char		*writebuf[DAHDI_MAX_NUM_BUFS]; /* write buffers */
+	u_char		*writebuf[DAHDI_MAX_NUM_BUFS]; /*!< write buffers */
 	int		inwritebuf;
 	int		outwritebuf;
-	wait_queue_head_t writebufq; /* write wait queue */
+	wait_queue_head_t writebufq; /*!< write wait queue */
 	
-	int		blocksize;	/* Block size */
+	int		blocksize;	/*!< Block size */
 
-	int		eventinidx;  /* out index in event buf (circular) */
-	int		eventoutidx;  /* in index in event buf (circular) */
-	unsigned int	eventbuf[DAHDI_MAX_EVENTSIZE];  /* event circ. buffer */
-	wait_queue_head_t eventbufq; /* event wait queue */
+	int		eventinidx;  /*!< out index in event buf (circular) */
+	int		eventoutidx;  /*!< in index in event buf (circular) */
+	unsigned int	eventbuf[DAHDI_MAX_EVENTSIZE];  /*!< event circ. buffer */
+	wait_queue_head_t eventbufq; /*!< event wait queue */
 	
-	wait_queue_head_t txstateq;	/* waiting on the tx state to change */
+	wait_queue_head_t txstateq;	/*!< waiting on the tx state to change */
 	
-	int		readn[DAHDI_MAX_NUM_BUFS];  /* # of bytes ready in read buf */
-	int		readidx[DAHDI_MAX_NUM_BUFS];  /* current read pointer */
-	int		writen[DAHDI_MAX_NUM_BUFS];  /* # of bytes ready in write buf */
-	int		writeidx[DAHDI_MAX_NUM_BUFS];  /* current write pointer */
+	int		readn[DAHDI_MAX_NUM_BUFS];  /*!< # of bytes ready in read buf */
+	int		readidx[DAHDI_MAX_NUM_BUFS];  /*!< current read pointer */
+	int		writen[DAHDI_MAX_NUM_BUFS];  /*!< # of bytes ready in write buf */
+	int		writeidx[DAHDI_MAX_NUM_BUFS];  /*!< current write pointer */
 	
-	int		numbufs;			/* How many buffers in channel */
-	int		txbufpolicy;			/* Buffer policy */
-	int		rxbufpolicy;			/* Buffer policy */
-	int		txdisable;				/* Disable transmitter */
-	int 	rxdisable;				/* Disable receiver */
+	int		numbufs;			/*!< How many buffers in channel */
+	int		txbufpolicy;			/*!< Buffer policy */
+	int		rxbufpolicy;			/*!< Buffer policy */
+	int		txdisable;				/*!< Disable transmitter */
+	int 	rxdisable;				/*!< Disable receiver */
 	
 	
 	/* Tone zone stuff */
-	struct dahdi_zone *curzone;		/* Zone for selecting tones */
-	int 	tonezone;				/* Tone zone for this channel */
-	struct dahdi_tone *curtone;		/* Current tone we're playing (if any) */
-	int		tonep;					/* Current position in tone */
-	struct dahdi_tone_state ts;		/* Tone state */
+	struct dahdi_zone *curzone;		/*!< Zone for selecting tones */
+	int 	tonezone;				/*!< Tone zone for this channel */
+	struct dahdi_tone *curtone;		/*!< Current tone we're playing (if any) */
+	int		tonep;					/*!< Current position in tone */
+	struct dahdi_tone_state ts;		/*!< Tone state */
 
 	/* Pulse dial stuff */
-	int	pdialcount;			/* pulse dial count */
+	int	pdialcount;			/*!< pulse dial count */
 
-	/* Ring cadence */
+	/*! Ring cadence */
 	int ringcadence[DAHDI_MAX_CADENCE];
-	int firstcadencepos;				/* Where to restart ring cadence */
+	int firstcadencepos;				/*!< Where to restart ring cadence */
 
 	/* Digit string dialing stuff */
-	int		digitmode;			/* What kind of tones are we sending? */
+	int		digitmode;			/*!< What kind of tones are we sending? */
 	char	txdialbuf[DAHDI_MAX_DTMF_BUF];
 	int 	dialing;
 	int	afterdialingtimer;
-	int		cadencepos;				/* Where in the cadence we are */
+	int		cadencepos;				/*!< Where in the cadence we are */
 
 	/* I/O Mask */	
-	int		iomask;  /* I/O Mux signal mask */
-	wait_queue_head_t sel;	/* thingy for select stuff */
+	int		iomask;  /*! I/O Mux signal mask */
+	wait_queue_head_t sel;	/*! thingy for select stuff */
 	
 	/* HDLC state machines */
 	struct fasthdlc_state txhdlc;
@@ -236,10 +242,10 @@ struct dahdi_chan {
 	int infcs;
 
 	/* Conferencing stuff */
-	int		confna;	/* conference number (alias) */
-	int		_confn;	/* Actual conference number */
-	int		confmode;  /* conference mode */
-	int		confmute; /* conference mute mode */
+	int		confna;	/*! conference number (alias) */
+	int		_confn;	/*! Actual conference number */
+	int		confmode;  /*! conference mode */
+	int		confmute; /*! conference mute mode */
 
 	/* Incoming and outgoing conference chunk queues for
 	   communicating between DAHDI master time and
@@ -247,50 +253,50 @@ struct dahdi_chan {
 	struct confq confin;
 	struct confq confout;
 
-	short	getlin[DAHDI_MAX_CHUNKSIZE];			/* Last transmitted samples */
-	unsigned char getraw[DAHDI_MAX_CHUNKSIZE];		/* Last received raw data */
-	short	getlin_lastchunk[DAHDI_MAX_CHUNKSIZE];	/* Last transmitted samples from last chunk */
-	short	putlin[DAHDI_MAX_CHUNKSIZE];			/* Last received samples */
-	unsigned char putraw[DAHDI_MAX_CHUNKSIZE];		/* Last received raw data */
-	short	conflast[DAHDI_MAX_CHUNKSIZE];			/* Last conference sample -- base part of channel */
-	short	conflast1[DAHDI_MAX_CHUNKSIZE];		/* Last conference sample  -- pseudo part of channel */
-	short	conflast2[DAHDI_MAX_CHUNKSIZE];		/* Previous last conference sample -- pseudo part of channel */
+	short	getlin[DAHDI_MAX_CHUNKSIZE];			/*!< Last transmitted samples */
+	unsigned char getraw[DAHDI_MAX_CHUNKSIZE];		/*!< Last received raw data */
+	short	getlin_lastchunk[DAHDI_MAX_CHUNKSIZE];	/*!< Last transmitted samples from last chunk */
+	short	putlin[DAHDI_MAX_CHUNKSIZE];			/*!< Last received samples */
+	unsigned char putraw[DAHDI_MAX_CHUNKSIZE];		/*!< Last received raw data */
+	short	conflast[DAHDI_MAX_CHUNKSIZE];			/*!< Last conference sample -- base part of channel */
+	short	conflast1[DAHDI_MAX_CHUNKSIZE];		/*!< Last conference sample  -- pseudo part of channel */
+	short	conflast2[DAHDI_MAX_CHUNKSIZE];		/*!< Previous last conference sample -- pseudo part of channel */
 	
 
-	/* Is echo cancellation enabled or disabled */
+	/*! Is echo cancellation enabled or disabled */
 	int		echocancel;
-	/* The echo canceler module that should be used to create an
+	/*! The echo canceler module that should be used to create an
 	   instance when this channel needs one */
 	const struct dahdi_echocan *ec_factory;
-	/* The echo canceler module that owns the instance currently
+	/*! The echo canceler module that owns the instance currently
 	   on this channel, if one is present */
 	const struct dahdi_echocan *ec_current;
-	/* The private state data of the echo canceler instance in use */
+	/*! The private state data of the echo canceler instance in use */
 	struct echo_can_state *ec_state;
 	echo_can_disable_detector_state_t txecdis;
 	echo_can_disable_detector_state_t rxecdis;
 	
-	int		echostate;		/* State of echo canceller */
-	int		echolastupdate;		/* Last echo can update pos */
-	int		echotimer;		/* Timer for echo update */
+	int		echostate;		/*!< State of echo canceller */
+	int		echolastupdate;		/*!< Last echo can update pos */
+	int		echotimer;		/*!< Timer for echo update */
 
 	/* RBS timings  */
-	int		prewinktime;  /* pre-wink time (ms) */
-	int		preflashtime;	/* pre-flash time (ms) */
-	int		winktime;  /* wink time (ms) */
-	int		flashtime;  /* flash time (ms) */
-	int		starttime;  /* start time (ms) */
-	int		rxwinktime;  /* rx wink time (ms) */
-	int		rxflashtime; /* rx flash time (ms) */
-	int		debouncetime;  /* FXS GS sig debounce time (ms) */
-	int		pulsebreaktime; /* pulse line open time (ms) */
-	int		pulsemaketime;  /* pulse line closed time (ms) */
-	int		pulseaftertime; /* pulse time between digits (ms) */
-
-	/* RING debounce timer */
+	int		prewinktime;  /*!< pre-wink time (ms) */
+	int		preflashtime;	/*!< pre-flash time (ms) */
+	int		winktime;  /*!< wink time (ms) */
+	int		flashtime;  /*!< flash time (ms) */
+	int		starttime;  /*!< start time (ms) */
+	int		rxwinktime;  /*!< rx wink time (ms) */
+	int		rxflashtime; /*!< rx flash time (ms) */
+	int		debouncetime;  /*!< FXS GS sig debounce time (ms) */
+	int		pulsebreaktime; /*!< pulse line open time (ms) */
+	int		pulsemaketime;  /*!< pulse line closed time (ms) */
+	int		pulseaftertime; /*!< pulse time between digits (ms) */
+
+	/*! RING debounce timer */
 	int	ringdebtimer;
 	
-	/* RING trailing detector to make sure a RING is really over */
+	/*! RING trailing detector to make sure a RING is really over */
 	int ringtrailer;
 
 	/* PULSE digit receiver stuff */
@@ -298,7 +304,7 @@ struct dahdi_chan {
 	int	pulsetimer;
 
 	/* RBS timers */
-	int 	itimerset;		/* what the itimer was set to last */
+	int 	itimerset;		/*!< what the itimer was set to last */
 	int 	itimer;
 	int 	otimer;
 	
@@ -314,10 +320,10 @@ struct dahdi_chan {
 	int txhooksig;
 	int kewlonhook;
 
-	/* Idle signalling if CAS signalling */
+	/*! Idle signalling if CAS signalling */
 	int idlebits;
 
-	int deflaw;		/* 1 = mulaw, 2=alaw, 0=undefined */
+	int deflaw;		/*! 1 = mulaw, 2=alaw, 0=undefined */
 	short *xlaw;
 #ifdef	OPTIMIZE_CHANMUTE
 	int chanmute;		/*!< no need for PCM data */
@@ -351,56 +357,56 @@ struct dahdi_echocan {
 int dahdi_register_echocan(const struct dahdi_echocan *ec);
 void dahdi_unregister_echocan(const struct dahdi_echocan *ec);
 
-/* Define the maximum block size */
+/*! Define the maximum block size */
 #define DAHDI_MAX_BLOCKSIZE	8192
 
-/* Define the default network block size */
+/*! Define the default network block size */
 #define DAHDI_DEFAULT_MTU_MRU	2048
 
 
-#define DAHDI_DEFAULT_WINKTIME	150	/* 150 ms default wink time */
-#define DAHDI_DEFAULT_FLASHTIME	750	/* 750 ms default flash time */
+#define DAHDI_DEFAULT_WINKTIME	150	/*!< 150 ms default wink time */
+#define DAHDI_DEFAULT_FLASHTIME	750	/*!< 750 ms default flash time */
 
-#define DAHDI_DEFAULT_PREWINKTIME	50	/* 50 ms before wink */
-#define DAHDI_DEFAULT_PREFLASHTIME 50	/* 50 ms before flash */
-#define DAHDI_DEFAULT_STARTTIME 1500	/* 1500 ms of start */
-#define DAHDI_DEFAULT_RINGTIME 2000	/* 2000 ms of ring on (start, FXO) */
+#define DAHDI_DEFAULT_PREWINKTIME	50	/*!< 50 ms before wink */
+#define DAHDI_DEFAULT_PREFLASHTIME 50	/*!< 50 ms before flash */
+#define DAHDI_DEFAULT_STARTTIME 1500	/*!< 1500 ms of start */
+#define DAHDI_DEFAULT_RINGTIME 2000	/*!< 2000 ms of ring on (start, FXO) */
 #if 0
-#define DAHDI_DEFAULT_RXWINKTIME 250	/* 250ms longest rx wink */
+#define DAHDI_DEFAULT_RXWINKTIME 250	/*!< 250ms longest rx wink */
 #endif
-#define DAHDI_DEFAULT_RXWINKTIME 300	/* 300ms longest rx wink (to work with the Atlas) */
-#define DAHDI_DEFAULT_RXFLASHTIME 1250	/* 1250ms longest rx flash */
-#define DAHDI_DEFAULT_DEBOUNCETIME 600	/* 600ms of FXS GS signalling debounce */
-#define DAHDI_DEFAULT_PULSEMAKETIME 50	/* 50 ms of line closed when dial pulsing */
-#define DAHDI_DEFAULT_PULSEBREAKTIME 50	/* 50 ms of line open when dial pulsing */
-#define DAHDI_DEFAULT_PULSEAFTERTIME 750	/* 750ms between dial pulse digits */
+#define DAHDI_DEFAULT_RXWINKTIME 300	/*!< 300ms longest rx wink (to work with the Atlas) */
+#define DAHDI_DEFAULT_RXFLASHTIME 1250	/*!< 1250ms longest rx flash */
+#define DAHDI_DEFAULT_DEBOUNCETIME 600	/*!< 600ms of FXS GS signalling debounce */
+#define DAHDI_DEFAULT_PULSEMAKETIME 50	/*!< 50 ms of line closed when dial pulsing */
+#define DAHDI_DEFAULT_PULSEBREAKTIME 50	/*!< 50 ms of line open when dial pulsing */
+#define DAHDI_DEFAULT_PULSEAFTERTIME 750	/*!< 750ms between dial pulse digits */
 
-#define DAHDI_MINPULSETIME (15 * 8)	/* 15 ms minimum */
+#define DAHDI_MINPULSETIME (15 * 8)	/*!< 15 ms minimum */
 
 #ifdef SHORT_FLASH_TIME
-#define DAHDI_MAXPULSETIME (80 * 8)	/* we need 80 ms, not 200ms, as we have a short flash */
+#define DAHDI_MAXPULSETIME (80 * 8)	/*!< we need 80 ms, not 200ms, as we have a short flash */
 #else
-#define DAHDI_MAXPULSETIME (200 * 8)	/* 200 ms maximum */
+#define DAHDI_MAXPULSETIME (200 * 8)	/*!< 200 ms maximum */
 #endif
 
 #define DAHDI_PULSETIMEOUT ((DAHDI_MAXPULSETIME / 8) + 50)
 
-#define DAHDI_RINGTRAILER (50 * 8)	/* Don't consider a ring "over" until it's been gone at least this
+#define DAHDI_RINGTRAILER (50 * 8)	/*!< Don't consider a ring "over" until it's been gone at least this
 									   much time */
 
-#define DAHDI_LOOPCODE_TIME 10000		/* send loop codes for 10 secs */
-#define DAHDI_ALARMSETTLE_TIME	5000	/* allow alarms to settle for 5 secs */
-#define DAHDI_AFTERSTART_TIME 500		/* 500ms after start */
+#define DAHDI_LOOPCODE_TIME 10000		/*!< send loop codes for 10 secs */
+#define DAHDI_ALARMSETTLE_TIME	5000	/*!< allow alarms to settle for 5 secs */
+#define DAHDI_AFTERSTART_TIME 500		/*!< 500ms after start */
 
-#define DAHDI_RINGOFFTIME 4000		/* Turn off ringer for 4000 ms */
-#define DAHDI_KEWLTIME 500		/* 500ms for kewl pulse */
-#define DAHDI_AFTERKEWLTIME 300    /* 300ms after kewl pulse */
+#define DAHDI_RINGOFFTIME 4000		/*!< Turn off ringer for 4000 ms */
+#define DAHDI_KEWLTIME 500		/*!< 500ms for kewl pulse */
+#define DAHDI_AFTERKEWLTIME 300    /*!< 300ms after kewl pulse */
 
-#define DAHDI_MAX_PRETRAINING   1000	/* 1000ms max pretraining time */
+#define DAHDI_MAX_PRETRAINING   1000	/*!< 1000ms max pretraining time */
 
 #ifdef	FXSFLASH
-#define DAHDI_FXSFLASHMINTIME	450	/* min 450ms */
-#define DAHDI_FXSFLASHMAXTIME	550	/* max 550ms */
+#define DAHDI_FXSFLASHMINTIME	450	/*!< min 450ms */
+#define DAHDI_FXSFLASHMAXTIME	550	/*!< max 550ms */
 #endif
 
 
@@ -412,12 +418,12 @@ struct dahdi_chardev {
 int dahdi_register_chardev(struct dahdi_chardev *dev);
 int dahdi_unregister_chardev(struct dahdi_chardev *dev);
 
-/* defines for transmit signalling */
+/*! \brief defines for transmit signalling */
 typedef enum {
-	DAHDI_TXSIG_ONHOOK,			/* On hook */
-	DAHDI_TXSIG_OFFHOOK,			/* Off hook */
-	DAHDI_TXSIG_START,				/* Start / Ring */
-	DAHDI_TXSIG_KEWL				/* Drop battery if possible */
+	DAHDI_TXSIG_ONHOOK,  /*!< On hook */
+	DAHDI_TXSIG_OFFHOOK, /*!< Off hook */
+	DAHDI_TXSIG_START,   /*!< Start / Ring */
+	DAHDI_TXSIG_KEWL     /*!< Drop battery if possible */
 } dahdi_txsig_t;
 
 typedef enum {
@@ -431,31 +437,31 @@ typedef enum {
 /* Span flags */
 #define DAHDI_FLAG_REGISTERED		(1 << 0)
 #define DAHDI_FLAG_RUNNING			(1 << 1)
-#define DAHDI_FLAG_RBS			(1 << 12)	/* Span uses RBS signalling */
+#define DAHDI_FLAG_RBS			(1 << 12)	/*!< Span uses RBS signalling */
 
 /* Channel flags */
-#define DAHDI_FLAG_DTMFDECODE		(1 << 2)	/* Channel supports native DTMF decode */
-#define DAHDI_FLAG_MFDECODE		(1 << 3)	/* Channel supports native MFr2 decode */
-#define DAHDI_FLAG_ECHOCANCEL		(1 << 4)	/* Channel supports native echo cancellation */
-
-#define DAHDI_FLAG_HDLC			(1 << 5)	/* Perform HDLC */
-#define DAHDI_FLAG_NETDEV			(1 << 6)	/* Send to network */
-#define DAHDI_FLAG_PSEUDO			(1 << 7)	/* Pseudo channel */
-#define DAHDI_FLAG_CLEAR			(1 << 8)	/* Clear channel */
-#define DAHDI_FLAG_AUDIO			(1 << 9)	/* Audio mode channel */
-
-#define DAHDI_FLAG_OPEN			(1 << 10)	/* Channel is open */
-#define DAHDI_FLAG_FCS			(1 << 11)	/* Calculate FCS */
+#define DAHDI_FLAG_DTMFDECODE		(1 << 2)	/*!< Channel supports native DTMF decode */
+#define DAHDI_FLAG_MFDECODE		(1 << 3)	/*!< Channel supports native MFr2 decode */
+#define DAHDI_FLAG_ECHOCANCEL		(1 << 4)	/*!< Channel supports native echo cancellation */
+
+#define DAHDI_FLAG_HDLC			(1 << 5)	/*!< Perform HDLC */
+#define DAHDI_FLAG_NETDEV			(1 << 6)	/*!< Send to network */
+#define DAHDI_FLAG_PSEUDO			(1 << 7)	/*!< Pseudo channel */
+#define DAHDI_FLAG_CLEAR			(1 << 8)	/*!< Clear channel */
+#define DAHDI_FLAG_AUDIO			(1 << 9)	/*!< Audio mode channel */
+
+#define DAHDI_FLAG_OPEN			(1 << 10)	/*!< Channel is open */
+#define DAHDI_FLAG_FCS			(1 << 11)	/*!< Calculate FCS */
 /* Reserve 12 for uniqueness with span flags */
-#define DAHDI_FLAG_LINEAR			(1 << 13)	/* Talk to user space in linear */
-#define DAHDI_FLAG_PPP			(1 << 14)	/* PPP is available */
+#define DAHDI_FLAG_LINEAR			(1 << 13)	/*!< Talk to user space in linear */
+#define DAHDI_FLAG_PPP			(1 << 14)	/*!< PPP is available */
 #define DAHDI_FLAG_T1PPP			(1 << 15)
-#define DAHDI_FLAG_SIGFREEZE		(1 << 16)	/* Freeze signalling */
-#define DAHDI_FLAG_NOSTDTXRX		(1 << 17)	/* Do NOT do standard transmit and receive on every interrupt */
-#define DAHDI_FLAG_LOOPED			(1 << 18)	/* Loopback the receive data from the channel to the transmit */
-#define DAHDI_FLAG_MTP2			(1 << 19)	/* Repeats last message in buffer and also discards repeating messages sent to us */
+#define DAHDI_FLAG_SIGFREEZE		(1 << 16)	/*!< Freeze signalling */
+#define DAHDI_FLAG_NOSTDTXRX		(1 << 17)	/*!< Do NOT do standard transmit and receive on every interrupt */
+#define DAHDI_FLAG_LOOPED			(1 << 18)	/*!< Loopback the receive data from the channel to the transmit */
+#define DAHDI_FLAG_MTP2			(1 << 19)	/*!< Repeats last message in buffer and also discards repeating messages sent to us */
 
-/* This is a redefinition of the flags from above to allow use of the kernel atomic bit testing and changing routines.
+/*! This is a redefinition of the flags from above to allow use of the kernel atomic bit testing and changing routines.
  * See the above descriptions for DAHDI_FLAG_....  for documentation about function. */
 enum {
 	DAHDI_FLAGBIT_REGISTERED = 0,
@@ -482,75 +488,75 @@ enum {
 
 struct dahdi_span {
 	spinlock_t lock;
-	void *pvt;			/* Private stuff */
-	char name[40];			/* Span name */
-	char desc[80];			/* Span description */
-	const char *spantype;		/* span type in text form */
-	const char *manufacturer;	/* span's device manufacturer */
-	char devicetype[80];		/* span's device type */
-	char location[40];		/* span device's location in system */
-	int deflaw;			/* Default law (DAHDI_MULAW or DAHDI_ALAW) */
-	int alarms;			/* Pending alarms on span */
+	void *pvt;			/*!< Private stuff */
+	char name[40];			/*!< Span name */
+	char desc[80];			/*!< Span description */
+	const char *spantype;		/*!< span type in text form */
+	const char *manufacturer;	/*!< span's device manufacturer */
+	char devicetype[80];		/*!< span's device type */
+	char location[40];		/*!< span device's location in system */
+	int deflaw;			/*!< Default law (DAHDI_MULAW or DAHDI_ALAW) */
+	int alarms;			/*!< Pending alarms on span */
 	int flags;
-	int irq;			/* IRQ for this span's hardware */
-	int lbo;			/* Span Line-Buildout */
-	int lineconfig;			/* Span line configuration */
-	int linecompat;			/* Span line compatibility */
-	int channels;			/* Number of channels in span */
-	int txlevel;			/* Tx level */
-	int rxlevel;			/* Rx level */
-	int syncsrc;			/* current sync src (gets copied here) */
-	unsigned int bpvcount;		/* BPV counter */
-	unsigned int crc4count;	        /* CRC4 error counter */
-	unsigned int ebitcount;		/* current E-bit error count */
-	unsigned int fascount;		/* current FAS error count */
-
-	int maintstat;			/* Maintenance state */
-	wait_queue_head_t maintq;	/* Maintenance queue */
-	int mainttimer;			/* Maintenance timer */
+	int irq;			/*!< IRQ for this span's hardware */
+	int lbo;			/*!< Span Line-Buildout */
+	int lineconfig;			/*!< Span line configuration */
+	int linecompat;			/*!< Span line compatibility */
+	int channels;			/*!< Number of channels in span */
+	int txlevel;			/*!< Tx level */
+	int rxlevel;			/*!< Rx level */
+	int syncsrc;			/*!< current sync src (gets copied here) */
+	unsigned int bpvcount;		/*!< BPV counter */
+	unsigned int crc4count;	        /*!< CRC4 error counter */
+	unsigned int ebitcount;		/*!< current E-bit error count */
+	unsigned int fascount;		/*!< current FAS error count */
+
+	int maintstat;			/*!< Maintenance state */
+	wait_queue_head_t maintq;	/*!< Maintenance queue */
+	int mainttimer;			/*!< Maintenance timer */
 	
-	int irqmisses;			/* Interrupt misses */
+	int irqmisses;			/*!< Interrupt misses */
 
-	int timingslips;			/* Clock slips */
+	int timingslips;			/*!< Clock slips */
 
-	struct dahdi_chan **chans;		/* Member channel structures */
+	struct dahdi_chan **chans;		/*!< Member channel structures */
 
 	/*   ==== Span Callback Operations ====   */
-	/* Req: Set the requested chunk size.  This is the unit in which you must
+	/*! Req: Set the requested chunk size.  This is the unit in which you must
 	   report results for conferencing, etc */
 	int (*setchunksize)(struct dahdi_span *span, int chunksize);
 
-	/* Opt: Configure the span (if appropriate) */
+	/*! Opt: Configure the span (if appropriate) */
 	int (*spanconfig)(struct dahdi_span *span, struct dahdi_lineconfig *lc);
 	
-	/* Opt: Start the span */
+	/*! Opt: Start the span */
 	int (*startup)(struct dahdi_span *span);
 	
-	/* Opt: Shutdown the span */
+	/*! Opt: Shutdown the span */
 	int (*shutdown)(struct dahdi_span *span);
 	
-	/* Opt: Enable maintenance modes */
+	/*! Opt: Enable maintenance modes */
 	int (*maint)(struct dahdi_span *span, int mode);
 
 #ifdef	DAHDI_SYNC_TICK
-	/* Opt: send sync to spans */
+	/*! Opt: send sync to spans */
 	int (*sync_tick)(struct dahdi_span *span, int is_master);
 #endif
 
 	/* ====  Channel Callback Operations ==== */
-	/* Opt: Set signalling type (if appropriate) */
+	/*! Opt: Set signalling type (if appropriate) */
 	int (*chanconfig)(struct dahdi_chan *chan, int sigtype);
 
-	/* Opt: Prepare a channel for I/O */
+	/*! Opt: Prepare a channel for I/O */
 	int (*open)(struct dahdi_chan *chan);
 
-	/* Opt: Close channel for I/O */
+	/*! Opt: Close channel for I/O */
 	int (*close)(struct dahdi_chan *chan);
 	
-	/* Opt: IOCTL */
+	/*! Opt: IOCTL */
 	int (*ioctl)(struct dahdi_chan *chan, unsigned int cmd, unsigned long data);
 	
-	/* Opt: Native echo cancellation (simple) */
+	/*! Opt: Native echo cancellation (simple) */
 	int (*echocan)(struct dahdi_chan *chan, int ecval);
 
 	int (*echocan_with_params)(struct dahdi_chan *chan, struct dahdi_echocanparams *ecp, struct dahdi_echocanparam *p);
@@ -561,31 +567,31 @@ struct dahdi_span {
 	   rbsbits function and we'll assert robbed bits for you.  Be sure to 
 	   set the DAHDI_FLAG_RBS in this case.  */
 
-	/* Opt: If the span uses A/B bits, set them here */
+	/*! Opt: If the span uses A/B bits, set them here */
 	int (*rbsbits)(struct dahdi_chan *chan, int bits);
 	
-	/* Option 2: If you don't know about sig bits, but do have their
+	/*! Option 2: If you don't know about sig bits, but do have their
 	   equivalents (i.e. you can disconnect battery, detect off hook,
 	   generate ring, etc directly) then you can just specify a
 	   sethook function, and we'll call you with appropriate hook states
 	   to set.  Still set the DAHDI_FLAG_RBS in this case as well */
 	int (*hooksig)(struct dahdi_chan *chan, dahdi_txsig_t hookstate);
 	
-	/* Option 3: If you can't use sig bits, you can write a function
+	/*! Option 3: If you can't use sig bits, you can write a function
 	   which handles the individual hook states  */
 	int (*sethook)(struct dahdi_chan *chan, int hookstate);
 	
-	/* Opt: Dacs the contents of chan2 into chan1 if possible */
+	/*! Opt: Dacs the contents of chan2 into chan1 if possible */
 	int (*dacs)(struct dahdi_chan *chan1, struct dahdi_chan *chan2);
 
-	/* Opt: Used to tell an onboard HDLC controller that there is data ready to transmit */
+	/*! Opt: Used to tell an onboard HDLC controller that there is data ready to transmit */
 	void (*hdlc_hard_xmit)(struct dahdi_chan *chan);
 
 	/* Used by DAHDI only -- no user servicable parts inside */
-	int spanno;			/* Span number for DAHDI */
-	int offset;			/* Offset within a given card */
-	int lastalarms;		/* Previous alarms */
-	/* If the watchdog detects no received data, it will call the
+	int spanno;			/*!< Span number for DAHDI */
+	int offset;			/*!< Offset within a given card */
+	int lastalarms;		/*!< Previous alarms */
+	/*! If the watchdog detects no received data, it will call the
 	   watchdog routine */
 	int (*watchdog)(struct dahdi_span *span, int cause);
 #ifdef CONFIG_DAHDI_WATCHDOG
@@ -619,7 +625,7 @@ struct dahdi_transcoder {
 	unsigned int srcfmts;
 	unsigned int dstfmts;
 	int (*operation)(struct dahdi_transcoder_channel *channel, int op);
-	/* Transcoder channels */
+	/*! Transcoder channels */
 	struct dahdi_transcoder_channel channels[0];
 };
 
@@ -634,103 +640,103 @@ struct dahdi_transcoder {
 
 
 struct dahdi_dynamic_driver {
-	/* Driver name (e.g. Eth) */
+	/*! Driver name (e.g. Eth) */
 	char name[20];
 
-	/* Driver description */
+	/*! Driver description */
 	char desc[80];
 
-	/* Create a new transmission pipe */
+	/*! Create a new transmission pipe */
 	void *(*create)(struct dahdi_span *span, char *address);
 
-	/* Destroy a created transmission pipe */
+	/*! Destroy a created transmission pipe */
 	void (*destroy)(void *tpipe);
 
-	/* Transmit a given message */
+	/*! Transmit a given message */
 	int (*transmit)(void *tpipe, unsigned char *msg, int msglen);
 
-	/* Flush any pending messages */
+	/*! Flush any pending messages */
 	int (*flush)(void);
 
 	struct dahdi_dynamic_driver *next;
 };
 
-/* Receive a dynamic span message */
+/*! \brief Receive a dynamic span message */
 void dahdi_dynamic_receive(struct dahdi_span *span, unsigned char *msg, int msglen);
 
-/* Register a dynamic driver */
+/*! \brief Register a dynamic driver */
 int dahdi_dynamic_register(struct dahdi_dynamic_driver *driver);
 
-/* Unregister a dynamic driver */
+/*! \brief Unregister a dynamic driver */
 void dahdi_dynamic_unregister(struct dahdi_dynamic_driver *driver);
 
-/* Receive on a span.  The DAHDI interface will handle all the calculations for
+/*! Receive on a span.  The DAHDI interface will handle all the calculations for
    all member channels of the span, pulling the data from the readchunk buffer */
 int dahdi_receive(struct dahdi_span *span);
 
-/* Prepare writechunk buffers on all channels for this span */
+/*! Prepare writechunk buffers on all channels for this span */
 int dahdi_transmit(struct dahdi_span *span);
 
-/* Abort the buffer currently being receive with event "event" */
+/*! Abort the buffer currently being receive with event "event" */
 void dahdi_hdlc_abort(struct dahdi_chan *ss, int event);
 
-/* Indicate to DAHDI that the end of frame was received and rotate buffers */
+/*! Indicate to DAHDI that the end of frame was received and rotate buffers */
 void dahdi_hdlc_finish(struct dahdi_chan *ss);
 
-/* Put a chunk of data into the current receive buffer */
+/*! Put a chunk of data into the current receive buffer */
 void dahdi_hdlc_putbuf(struct dahdi_chan *ss, unsigned char *rxb, int bytes);
 
-/* Get a chunk of data from the current transmit buffer.  Returns -1 if no data
+/*! Get a chunk of data from the current transmit buffer.  Returns -1 if no data
  * is left to send, 0 if there is data remaining in the current message to be sent
  * and 1 if the currently transmitted message is now done */
 int dahdi_hdlc_getbuf(struct dahdi_chan *ss, unsigned char *bufptr, unsigned int *size);
 
 
-/* Register a span.  Returns 0 on success, -1 on failure.  Pref-master is non-zero if
+/*! Register a span.  Returns 0 on success, -1 on failure.  Pref-master is non-zero if
    we should have preference in being the master device */
 int dahdi_register(struct dahdi_span *span, int prefmaster);
 
-/* Allocate / free memory for a transcoder */
+/*! Allocate / free memory for a transcoder */
 struct dahdi_transcoder *dahdi_transcoder_alloc(int numchans);
 void dahdi_transcoder_free(struct dahdi_transcoder *ztc);
 
-/* Register a transcoder */
+/*! \brief Register a transcoder */
 int dahdi_transcoder_register(struct dahdi_transcoder *tc);
 
-/* Unregister a transcoder */
+/*! \brief Unregister a transcoder */
 int dahdi_transcoder_unregister(struct dahdi_transcoder *tc);
 
-/* Alert a transcoder */
+/*! \brief Alert a transcoder */
 int dahdi_transcoder_alert(struct dahdi_transcoder_channel *ztc);
 
-/* Unregister a span */
+/*! \brief Unregister a span */
 int dahdi_unregister(struct dahdi_span *span);
 
-/* Gives a name to an LBO */
+/*! \brief Gives a name to an LBO */
 char *dahdi_lboname(int lbo);
 
-/* Tell DAHDI about changes in received rbs bits */
+/*! \brief Tell DAHDI about changes in received rbs bits */
 void dahdi_rbsbits(struct dahdi_chan *chan, int bits);
 
-/* Tell DAHDI abou changes in received signalling */
+/*! \brief Tell DAHDI abou changes in received signalling */
 void dahdi_hooksig(struct dahdi_chan *chan, dahdi_rxsig_t rxsig);
 
-/* Queue an event on a channel */
+/*! \brief Queue an event on a channel */
 void dahdi_qevent_nolock(struct dahdi_chan *chan, int event);
 
-/* Queue an event on a channel, locking it first */
+/*! \brief Queue an event on a channel, locking it first */
 void dahdi_qevent_lock(struct dahdi_chan *chan, int event);
 
-/* Notify a change possible change in alarm status on a channel */
+/*! \brief Notify a change possible change in alarm status on a channel */
 void dahdi_alarm_channel(struct dahdi_chan *chan, int alarms);
 
-/* Notify a change possible change in alarm status on a span */
+/*! \brief Notify a change possible change in alarm status on a span */
 void dahdi_alarm_notify(struct dahdi_span *span);
 
-/* Initialize a tone state */
+/*! \brief Initialize a tone state */
 void dahdi_init_tone_state(struct dahdi_tone_state *ts, struct dahdi_tone *zt);
 
-/* Get a given MF tone struct, suitable for dahdi_tone_nextsample. */
+/*! \brief Get a given MF tone struct, suitable for dahdi_tone_nextsample. */
 struct dahdi_tone *dahdi_mf_tone(const struct dahdi_chan *chan, char digit, int digitmode);
 
 /* Echo cancel a receive and transmit chunk for a given channel.  This
@@ -756,13 +762,13 @@ extern u_char __dahdi_lin2mu[16384];
 extern u_char __dahdi_lin2a[16384];
 #endif
 
-/* Used by dynamic DAHDI -- don't use directly */
+/*! \brief Used by dynamic DAHDI -- don't use directly */
 void dahdi_set_dynamic_ioctl(int (*func)(unsigned int cmd, unsigned long data));
 
-/* Used by DAHDI HPEC module -- don't use directly */
+/*! \brief Used by DAHDI HPEC module -- don't use directly */
 void dahdi_set_hpec_ioctl(int (*func)(unsigned int cmd, unsigned long data));
 
-/* Used privately by DAHDI.  Avoid touching directly */
+/*! \brief Used privately by DAHDI.  Avoid touching directly */
 struct dahdi_tone {
 	int fac1;
 	int init_v2_1;
@@ -772,7 +778,7 @@ struct dahdi_tone {
 	int init_v2_2;
 	int init_v3_2;
 
-	int tonesamples;		/* How long to play this tone before 
+	int tonesamples;		/*!< How long to play this tone before 
 					   going to the next (in samples) */
 	struct dahdi_tone *next;		/* Next tone in this sequence */