staging: dgnc: clean up header comments

TODO file has task: remove unnecessary comments. Driver uses some
custom comment format. Driver would be better if it used kernel doc
format.

Audit header file comments. Replace struct comments with kernel doc
format comments. Remove unnecessary comments.
Signed-off-by: Tobin C. Harding <me@tobin.cc>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

drivers/staging/dgnc/dgnc_cls.h

@@ -16,24 +16,21 @@
 #ifndef __DGNC_CLS_H
 #define __DGNC_CLS_H
 
-/************************************************************************
- * Per channel/port Classic UART structure				*
- ************************************************************************
- *		Base Structure Entries Usage Meanings to Host		*
- *									*
- *	W = read write		R = read only				*
- *			U = Unused.					*
- ************************************************************************/
-
-/*
- * txrx    : WR RHR/THR - Holding reg
- * ier     : WR IER - Interrupt Enable Reg
- * isr_fcr : WR ISR/FCR - Interrupt Status Reg/Fifo Control Reg
- * lcr     : WR LCR - Line Control Reg
- * mcr     : WR MCR - Modem Control Reg
- * lsr     : WR LSR - Line Status Reg
- * msr     : WR MSG - Modem Status Reg
- * spr     : WR SPR - Scratch pad Reg
+/**
+ * struct cls_uart_struct - Per channel/port Classic UART.
+ *
+ * key - W = read write
+ *     - R = read only
+ *     - U = unused
+ *
+ * @txrx: (WR) Holding Register.
+ * @ier: (WR) Interrupt Enable Register.
+ * @isr_fcr: (WR) Interrupt Status Register/Fifo Control Register.
+ * @lcr: (WR) Line Control Register.
+ * @mcr: (WR) Modem Control Register.
+ * @lsr: (WR) Line Status Register.
+ * @msr: (WR) Modem Status Register.
+ * @spr: (WR) Scratch Pad Register.
  */
 struct cls_uart_struct {
 	u8 txrx;
@@ -74,9 +71,6 @@ struct cls_uart_struct {
 #define UART_EXAR654_IER_RTSDTR   0x40    /* Output Interrupt Enable */
 #define UART_EXAR654_IER_CTSDSR   0x80    /* Input Interrupt Enable */
 
-/*
- * Our Global Variables
- */
 extern struct board_ops dgnc_cls_ops;
 
 #endif

drivers/staging/dgnc/dgnc_driver.h

@@ -11,8 +11,6 @@
  * but WITHOUT ANY WARRANTY, EXPRESS OR IMPLIED; without even the
  * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  * PURPOSE.  See the GNU General Public License for more details.
- *
- * Driver includes
  */
 
 #ifndef __DGNC_DRIVER_H
@@ -24,8 +22,6 @@
 
 #include "digi.h"		/* Digi specific ioctl header */
 
-/* Driver defines */
-
 /* Driver identification and error statements */
 #define	PROCSTR		"dgnc"			/* /proc entries */
 #define	DEVSTR		"/dev/dg/dgnc"		/* /dev entries */
@@ -53,10 +49,7 @@
 #define PORT_NUM(dev)	((dev) & 0x7f)
 #define IS_PRINT(dev)	(((dev) & 0xff) >= 0x80)
 
-/*
- *MAX number of stop characters we will send
- * when our read queue is getting full
- */
+/* MAX number of stop characters sent when our read queue is getting full */
 #define MAX_STOPS_SENT 5
 
 /* 4 extra for alignment play space */
@@ -82,27 +75,24 @@
 #endif
 
 /* All the possible states the driver can be while being loaded. */
-
 enum {
 	DRIVER_INITIALIZED = 0,
 	DRIVER_READY
 };
 
 /* All the possible states the board can be while booting up. */
-
 enum {
 	BOARD_FAILED = 0,
 	BOARD_FOUND,
 	BOARD_READY
 };
 
-/* Structures and closely related defines. */
-
 struct dgnc_board;
 struct channel_t;
 
-/* Per board operations structure */
-
+/**
+ * struct board_ops - Per board operations.
+ */
 struct board_ops {
 	void (*tasklet)(unsigned long data);
 	irqreturn_t (*intr)(int irq, void *voidbrd);
@@ -128,77 +118,109 @@ struct board_ops {
 
 #define BD_IS_PCI_EXPRESS     0x0001	  /* Is a PCI Express board */
 
-/*	Per-board information */
-
-struct dgnc_board {
-	int		magic;		/* Board Magic number. */
-	int		boardnum;	/* Board number: 0-32 */
-
-	int		type;		/* Type of board */
-	char		*name;		/* Product Name */
-	struct pci_dev	*pdev;		/* Pointer to the pci_dev struct */
-	unsigned long	bd_flags;	/* Board flags */
-	u16		vendor;		/* PCI vendor ID */
-	u16		device;		/* PCI device ID */
-	u16		subvendor;	/* PCI subsystem vendor ID */
-	u16		subdevice;	/* PCI subsystem device ID */
-	unsigned char	rev;		/* PCI revision ID */
-	uint		pci_bus;	/* PCI bus value */
-	uint		pci_slot;	/* PCI slot value */
-	uint		maxports;	/* MAX ports this board can handle */
-	unsigned char	dvid;		/* Board specific device id */
-	unsigned char	vpd[128];	/* VPD of board, if found */
-	unsigned char	serial_num[20];	/* Serial number of board,
-					 * if found in VPD
+/**
+ * struct dgnc_board - Per board information.
+ * @magic: Board magic number.
+ * @boardnum: Board number (0 - 32).
+ *
+ * @type: Type of board.
+ * @name: Product name.
+ * @pdev: Pointer to the pci_dev structure.
+ * @bd_flags: Board flags.
+ * @vendor: PCI vendor ID.
+ * @device: PCI device ID.
+ * @subvendor: PCI subsystem vendor ID.
+ * @subdevice: PCI subsystem device ID.
+ * @rev: PCI revision ID.
+ * @pci_bus: PCI bus value.
+ * @pci_slot: PCI slot value.
+ * @maxports: Maximum ports this board can handle.
+ * @dvid: Board specific device ID.
+ * @vpd: VPD of this board, if found.
+ * @serial_num: Serial number of this board, if found in VPD.
+ * @bd_lock: Used to protect board.
+ * @bd_intr_lock: Protect poller tasklet and interrupt routine from each other.
+ * @state: State of the card.
+ * @state_wait: Queue to sleep on for state change.
+ * @helper_tasklet: Poll helper tasklet.
+ * @nasync: Number of ports on card.
+ * @irq: Interrupt request number.
+ * @membase: Start of base memory of the card.
+ * @membase_end: End of base memory of the card.
+ * @iobase: Start of IO base of the card.
+ * @iobase_end: End of IO base of the card.
+ * @bd_uart_offset: Space between each UART.
+ * @channels: array of pointers to our channels.
+ * @serial_driver: Pointer to the serial driver.
+ * @serial_name: Serial driver name.
+ * @print_dirver: Pointer to the print driver.
+ * @print_name: Print driver name.
+ * @dpatype: Board type as defined by DPA.
+ * @dpastatus: Board status as defined by DPA.
+ * @bd_dividend: Board/UART's specific dividend.
+ * @bd_ops: Pointer to board operations structure.
+ * @proc_entry_pointer: Proc/<board> entry
+ * @dgnc_board_table: Proc/<board> entry
  */
+struct dgnc_board {
+	int		magic;
+	int		boardnum;
 
-	spinlock_t	bd_lock;	/* Used to protect board */
+	int		type;
+	char		*name;
+	struct pci_dev	*pdev;
+	unsigned long	bd_flags;
+	u16		vendor;
+	u16		device;
+	u16		subvendor;
+	u16		subdevice;
+	unsigned char	rev;
+	uint		pci_bus;
+	uint		pci_slot;
+	uint		maxports;
+	unsigned char	dvid;
+	unsigned char	vpd[128];
+	unsigned char	serial_num[20];
 
-	spinlock_t	bd_intr_lock;	/* Used to protect the poller tasklet
-					 * and the interrupt routine from each
-					 * other.
-					 */
+	/* used to protect the board */
+	spinlock_t	bd_lock;
 
-	uint		state;		/* State of card. */
-	wait_queue_head_t state_wait;	/* Place to sleep on for state change */
+	/*  Protect poller tasklet and interrupt routine from each other. */
+	spinlock_t	bd_intr_lock;
 
-	struct		tasklet_struct helper_tasklet; /* Poll helper tasklet */
+	uint		state;
+	wait_queue_head_t state_wait;
 
-	uint		nasync;		/* Number of ports on card */
+	struct tasklet_struct helper_tasklet;
 
-	uint		irq;		/* Interrupt request number */
+	uint		nasync;
 
-	ulong		membase;	/* Start of base memory of the card */
-	ulong		membase_end;	/* End of base memory of the card */
+	uint		irq;
 
-	u8 __iomem	*re_map_membase; /* Remapped memory of the card */
+	ulong		membase;
+	ulong		membase_end;
 
-	ulong		iobase;		/* Start of io base of the card */
-	ulong		iobase_end;	/* End of io base of the card */
+	u8 __iomem	*re_map_membase;
 
-	uint		bd_uart_offset;	/* Space between each UART */
+	ulong		iobase;
+	ulong		iobase_end;
 
-	struct channel_t *channels[MAXPORTS];	/* array of pointers
-						 * to our channels.
-						 */
+	uint		bd_uart_offset;
+
+	struct channel_t *channels[MAXPORTS];
 
 	struct tty_driver *serial_driver;
 	char		serial_name[200];
 	struct tty_driver *print_driver;
 	char		print_name[200];
 
-	u16		dpatype;	/* The board "type",
-					 * as defined by DPA
-					 */
-	u16		dpastatus;	/* The board "status",
-					 * as defined by DPA
-					 */
+	u16		dpatype;
+	u16		dpastatus;
 
-	uint		bd_dividend;	/* Board/UARTs specific dividend */
+	uint		bd_dividend;
 
 	struct board_ops *bd_ops;
 
-	/* /proc/<board> entries */
 	struct proc_dir_entry *proc_entry_pointer;
 	struct dgnc_proc_entry *dgnc_board_table;
 
@@ -221,17 +243,25 @@ struct dgnc_board {
 
 struct device;
 
-/* Structure for terminal or printer unit. */
+/**
+ * struct un_t - terminal or printer unit
+ * @magic: Unit magic number.
+ * @un_open_count: Counter of opens to port.
+ * @un_tty: Pointer to unit tty structure.
+ * @un_flags: Unit flags.
+ * @un_flags_wait: Place to sleep to wait on unit.
+ * @un_dev: Minor device number.
+ */
 struct un_t {
-	int	magic;		/* Unit Magic Number. */
+	int	magic;
 	struct	channel_t *un_ch;
 	ulong	un_time;
 	uint	un_type;
-	uint	un_open_count;		/* Counter of opens to port */
-	struct tty_struct *un_tty;	/* Pointer to unit tty structure */
-	uint	un_flags;		/* Unit flags */
-	wait_queue_head_t un_flags_wait; /* Place to sleep to wait on unit */
-	uint	un_dev;			/* Minor device number */
+	uint	un_open_count;
+	struct tty_struct *un_tty;
+	uint	un_flags;
+	wait_queue_head_t un_flags_wait;
+	uint	un_dev;
 	struct device *un_sysfs;
 };
 
@@ -263,102 +293,139 @@ struct un_t {
 #define EQUEUESIZE	RQUEUESIZE
 #define WQUEUESIZE	(WQUEUEMASK + 1)
 
-/* Channel information structure. */
+/**
+ * struct channel_t - Channel information.
+ * @magic: Channel magic number.
+ * @dgnc_board: Pointer to board structure.
+ * @ch_bd: Transparent print structure.
+ * @ch_tun: Terminal unit information.
+ * @ch_pun: Printer unit information.
+ * @ch_lock: Provide for serialization.
+ * @ch_flags_wait: Channel flags wait queue.
+ * @ch_portnum: Port number, 0 offset.
+ * @ch_open_count: Open count.
+ * @ch_flags: Channel flags.
+ * @ch_close_delay: How long we should drop RTS/DTR for.
+ * @ch_cpstime: Time for CPS calculations.
+ * @ch_c_iflag: Channel iflags.
+ * @ch_c_cflag: Channel cflags.
+ * @ch_c_oflag: Channel oflags.
+ * @ch_c_lflag: Channel lflags.
+ * @ch_stopc: Stop character.
+ * @ch_startc: Start character.
+ * @ch_old_baud: Cache of the current baud rate.
+ * @ch_custom_speed: Custom baud rate, if set.
+ * @ch_wopen: Waiting for open process count.
+ * @ch_mostat: FEP output modem status.
+ * @ch_mistat: FEP input modem status.
+ * @chc_neo_uart: Pointer to the mapped neo UART struct
+ * @ch_cls_uart:  Pointer to the mapped cls UART struct
+ * @ch_cached_lsr: Cached value of the LSR register.
+ * @ch_rqueue: Read queue buffer, malloc'ed.
+ * @ch_r_head: Head location of the read queue.
+ * @ch_r_tail: Tail location of the read queue.
+ * @ch_equeue: Error queue buffer, malloc'ed.
+ * @ch_e_head: Head location of the error queue.
+ * @ch_e_tail: Tail location of the error queue.
+ * @ch_wqueue: Write queue buffer, malloc'ed.
+ * @ch_w_head: Head location of the write queue.
+ * @ch_w_tail: Tail location of the write queue.
+ * @ch_rxcount: Total of data received so far.
+ * @ch_txcount: Total of data transmitted so far.
+ * @ch_r_tlevel: Receive trigger level.
+ * @ch_t_tlevel: Transmit trigger level.
+ * @ch_r_watermark: Receive water mark.
+ * @ch_stop_sending_break: Time we should STOP sending a break.
+ * @ch_stops_sent: How many times I have send a stop character to try
+ *                 to stop the other guy sending.
+ * @ch_err_parity: Count of parity
+ * @ch_err_frame: Count of framing errors on channel.
+ * @ch_err_break: Count of breaks on channel.
+ * @ch_err_overrun: Count of overruns on channel.
+ * @ch_xon_sends: Count of xons transmitted.
+ * @ch_xoff_sends: Count of xoffs transmitted.
+ * @proc_entry_pointer: Proc/<board>/<channel> entry.
+ * @dgnc_channel_table: Proc/<board>/<channel> entry.
+ */
 struct channel_t {
-	int magic;			/* Channel Magic Number	*/
-	struct dgnc_board *ch_bd;	/* Board structure pointer */
-	struct digi_t	ch_digi;	/* Transparent Print structure  */
-	struct un_t	ch_tun;		/* Terminal unit info */
-	struct un_t	ch_pun;		/* Printer unit info */
+	int magic;
+	struct dgnc_board *ch_bd;
+	struct digi_t	ch_digi;
+	struct un_t	ch_tun;
+	struct un_t	ch_pun;
 
 	spinlock_t	ch_lock; /* provide for serialization */
 	wait_queue_head_t ch_flags_wait;
 
-	uint		ch_portnum;	/* Port number, 0 offset. */
-	uint		ch_open_count;	/* open count */
-	uint		ch_flags;	/* Channel flags */
+	uint		ch_portnum;
+	uint		ch_open_count;
+	uint		ch_flags;
 
-	ulong		ch_close_delay;	/* How long we should
-					 * drop RTS/DTR for
-					 */
+	ulong		ch_close_delay;
 
-	ulong		ch_cpstime;	/* Time for CPS calculations */
+	ulong		ch_cpstime;
 
-	tcflag_t	ch_c_iflag;	/* channel iflags */
-	tcflag_t	ch_c_cflag;	/* channel cflags */
-	tcflag_t	ch_c_oflag;	/* channel oflags */
-	tcflag_t	ch_c_lflag;	/* channel lflags */
-	unsigned char	ch_stopc;	/* Stop character */
-	unsigned char	ch_startc;	/* Start character */
+	tcflag_t	ch_c_iflag;
+	tcflag_t	ch_c_cflag;
+	tcflag_t	ch_c_oflag;
+	tcflag_t	ch_c_lflag;
+	unsigned char	ch_stopc;
+	unsigned char	ch_startc;
 
-	uint		ch_old_baud;	/* Cache of the current baud */
-	uint		ch_custom_speed;/* Custom baud, if set */
+	uint		ch_old_baud;
+	uint		ch_custom_speed;
 
-	uint		ch_wopen;	/* Waiting for open process cnt */
+	uint		ch_wopen;
 
-	unsigned char	ch_mostat;	/* FEP output modem status */
-	unsigned char	ch_mistat;	/* FEP input modem status */
+	unsigned char	ch_mostat;
+	unsigned char	ch_mistat;
 
-	struct neo_uart_struct __iomem *ch_neo_uart;	/* Pointer to the
-							 * "mapped" UART struct
-							 */
-	struct cls_uart_struct __iomem *ch_cls_uart;	/* Pointer to the
-							 * "mapped" UART struct
-							 */
+	struct neo_uart_struct __iomem *ch_neo_uart;
+	struct cls_uart_struct __iomem *ch_cls_uart;
 
-	unsigned char	ch_cached_lsr;	/* Cached value of the LSR register */
+	unsigned char	ch_cached_lsr;
 
-	unsigned char	*ch_rqueue;	/* Our read queue buffer - malloc'ed */
-	ushort		ch_r_head;	/* Head location of the read queue */
-	ushort		ch_r_tail;	/* Tail location of the read queue */
+	unsigned char	*ch_rqueue;
+	ushort		ch_r_head;
+	ushort		ch_r_tail;
 
-	unsigned char	*ch_equeue;	/* Our error queue buffer - malloc'ed */
-	ushort		ch_e_head;	/* Head location of the error queue */
-	ushort		ch_e_tail;	/* Tail location of the error queue */
+	unsigned char	*ch_equeue;
+	ushort		ch_e_head;
+	ushort		ch_e_tail;
 
-	unsigned char	*ch_wqueue;	/* Our write queue buffer - malloc'ed */
-	ushort		ch_w_head;	/* Head location of the write queue */
-	ushort		ch_w_tail;	/* Tail location of the write queue */
+	unsigned char	*ch_wqueue;
+	ushort		ch_w_head;
+	ushort		ch_w_tail;
 
-	ulong		ch_rxcount;	/* total of data received so far */
-	ulong		ch_txcount;	/* total of data transmitted so far */
+	ulong		ch_rxcount;
+	ulong		ch_txcount;
 
-	unsigned char	ch_r_tlevel;	/* Receive Trigger level */
-	unsigned char	ch_t_tlevel;	/* Transmit Trigger level */
+	unsigned char	ch_r_tlevel;
+	unsigned char	ch_t_tlevel;
 
-	unsigned char	ch_r_watermark;	/* Receive Watermark */
+	unsigned char	ch_r_watermark;
 
-	ulong		ch_stop_sending_break;	/* Time we should STOP
-						 * sending a break
-						 */
+	ulong		ch_stop_sending_break;
+	uint		ch_stops_sent;
 
-	uint		ch_stops_sent;	/* How many times I have sent a stop
-					 * character to try to stop the other
-					 * guy sending.
-					 */
-	ulong		ch_err_parity;	/* Count of parity errors on channel */
-	ulong		ch_err_frame;	/* Count of framing errors on channel */
-	ulong		ch_err_break;	/* Count of breaks on channel */
-	ulong		ch_err_overrun; /* Count of overruns on channel */
+	ulong		ch_err_parity;
+	ulong		ch_err_frame;
+	ulong		ch_err_break;
+	ulong		ch_err_overrun;
 
-	ulong		ch_xon_sends;	/* Count of xons transmitted */
-	ulong		ch_xoff_sends;	/* Count of xoffs transmitted */
+	ulong		ch_xon_sends;
+	ulong		ch_xoff_sends;
 
-	/* /proc/<board>/<channel> entries */
 	struct proc_dir_entry *proc_entry_pointer;
 	struct dgnc_proc_entry *dgnc_channel_table;
 
 };
 
-/* Our Global Variables. */
-
 extern uint		dgnc_major;		/* Our driver/mgmt major */
 extern int		dgnc_poll_tick;		/* Poll interval - 20 ms */
 extern spinlock_t	dgnc_global_lock;	/* Driver global spinlock */
 extern spinlock_t	dgnc_poll_lock;		/* Poll scheduling lock */
 extern uint		dgnc_num_boards;	/* Total number of boards */
-extern struct dgnc_board *dgnc_board[MAXBOARDS];/* Array of board
-						 * structs
-						 */
+extern struct dgnc_board *dgnc_board[MAXBOARDS];/* Array of boards */
 
 #endif

drivers/staging/dgnc/dgnc_neo.h

@@ -18,38 +18,57 @@
 
 #include "dgnc_driver.h"
 
-/*
- *	Per channel/port NEO UART structure
- *	Base Structure Entries Usage Meanings to Host
+/**
+ * struct neo_uart_struct - Per channel/port NEO UART structure
+ *
+ * key - W = read write
+ *     - R = read only
+ *     - U = unused
  *
- *	W = read write		R = read only
- *			U = Unused.
+ * @txrx: (RW) Holding Register.
+ * @ier: (RW) Interrupt Enable Register.
+ * @isr_fcr: (RW) Interrupt Status Reg/Fifo Control Register.
+ * @lcr: (RW) Line Control Register.
+ * @mcr: (RW) Modem Control Register.
+ * @lsr: (RW) Line Status Register.
+ * @msr: (RW) Modem Status Register.
+ * @spr: (RW) Scratch Pad Register.
+ * @fctr: (RW) Feature Control Register.
+ * @efr: (RW) Enhanced Function Register.
+ * @tfifo: (RW) Transmit FIFO Register.
+ * @rfifo: (RW) Receive  FIFO Register.
+ * @xoffchar1: (RW) XOff Character 1 Register.
+ * @xoffchar2: (RW) XOff Character 2 Register.
+ * @xonchar1: (RW) Xon Character 1 Register.
+ * @xonchar2: (RW) XOn Character 2 Register.
+ * @reserved1: (U) Reserved by Exar.
+ * @txrxburst: (RW)  64 bytes of RX/TX FIFO Data.
+ * @reserved2: (U) Reserved by Exar.
+ * @rxburst_with_errors: (R) bytes of RX FIFO Data + LSR.
  */
-
 struct neo_uart_struct {
-	u8 txrx;	/* WR  RHR/THR - Holding Reg */
-	u8 ier;		/* WR  IER - Interrupt Enable Reg */
-	u8 isr_fcr;	/* WR  ISR/FCR - Interrupt Status Reg/Fifo
-			 * Control Reg
-			 */
-	u8 lcr;		/* WR  LCR - Line Control Reg */
-	u8 mcr;		/* WR  MCR - Modem Control Reg */
-	u8 lsr;		/* WR  LSR - Line Status Reg */
-	u8 msr;		/* WR  MSR - Modem Status Reg */
-	u8 spr;		/* WR  SPR - Scratch Pad Reg */
-	u8 fctr;	/* WR  FCTR - Feature Control Reg */
-	u8 efr;		/* WR  EFR - Enhanced Function Reg */
-	u8 tfifo;	/* WR  TXCNT/TXTRG - Transmit FIFO Reg */
-	u8 rfifo;	/* WR  RXCNT/RXTRG - Receive  FIFO Reg */
-	u8 xoffchar1;	/* WR  XOFF 1 - XOff Character 1 Reg */
-	u8 xoffchar2;	/* WR  XOFF 2 - XOff Character 2 Reg */
-	u8 xonchar1;	/* WR  XON 1 - Xon Character 1 Reg */
-	u8 xonchar2;	/* WR  XON 2 - XOn Character 2 Reg */
-
-	u8 reserved1[0x2ff - 0x200]; /* U   Reserved by Exar */
-	u8 txrxburst[64];	     /* RW  64 bytes of RX/TX FIFO Data */
-	u8 reserved2[0x37f - 0x340]; /* U   Reserved by Exar */
-	u8 rxburst_with_errors[64];  /* R  64 bytes of RX FIFO Data + LSR */
+	u8 txrx;
+	u8 ier;
+	u8 isr_fcr;
+
+	u8 lcr;
+	u8 mcr;
+	u8 lsr;
+	u8 msr;
+	u8 spr;
+	u8 fctr;
+	u8 efr;
+	u8 tfifo;
+	u8 rfifo;
+	u8 xoffchar1;
+	u8 xoffchar2;
+	u8 xonchar1;
+	u8 xonchar2;
+
+	u8 reserved1[0x2ff - 0x200];
+	u8 txrxburst[64];
+	u8 reserved2[0x37f - 0x340];
+	u8 rxburst_with_errors[64];
 };
 
 /* Where to read the extended interrupt register (32bits instead of 8bits) */
@@ -151,8 +170,6 @@ struct neo_uart_struct {
 #define UART_17158_IER_RTSDTR	0x40	/* Output Interrupt Enable */
 #define UART_17158_IER_CTSDSR	0x80	/* Input Interrupt Enable */
 
-/* Our Global Variables */
-
 extern struct board_ops dgnc_neo_ops;
 
 #endif

drivers/staging/dgnc/dgnc_pci.h

@@ -16,7 +16,8 @@
 #ifndef __DGNC_PCI_H
 #define __DGNC_PCI_H
 
-#define PCIMAX 32			/* maximum number of PCI boards */
+/* Maximum number of PCI boards */
+#define PCIMAX 32
 
 #define DIGI_VID				0x114F
 
@@ -59,10 +60,10 @@
 #define PCI_DEVICE_NEO_EXPRESS_8RJ45_PCI_NAME	"Neo 8 PCI Express RJ45"
 #define PCI_DEVICE_NEO_EXPRESS_4_IBM_PCI_NAME	"Neo 4 PCI Express IBM"
 
-/* Size of Memory and I/O for PCI (4 K) */
+/* Size of memory and I/O for PCI (4 K) */
 #define PCI_RAM_SIZE				0x1000
 
-/* Size of Memory (2MB) */
+/* Size of memory (2MB) */
 #define PCI_MEM_SIZE				0x1000
 
 #endif

drivers/staging/dgnc/digi.h

@@ -45,8 +45,7 @@
 #define DIGI_SETAW	(('e' << 8) | 96)	/* Drain & set params */
 #define DIGI_SETAF	(('e' << 8) | 97)	/* Drain, flush & set params */
 #define DIGI_GET_NI_INFO (('d' << 8) | 250)	/* Non-intelligent state info */
-#define DIGI_LOOPBACK (('d' << 8) | 252)	/*
-						 * Enable/disable UART
+#define DIGI_LOOPBACK (('d' << 8) | 252)	/* Enable/disable UART
 						 * internal loopback
 						 */
 #define DIGI_FAST	0x0002		/* Fast baud rates */
@@ -64,50 +63,77 @@
 /*
  * Structure used with ioctl commands for DIGI parameters.
  */
+/**
+ * struct digi_t - Ioctl commands for DIGI parameters.
+ * @digi_flags: Flags.
+ * @digi_maxcps: Maximum printer CPS.
+ * @digi_maxchar: Maximum characters in the print queue.
+ * @digi_bufsize: Buffer size.
+ * @digi_onlen: Length of ON string.
+ * @digi_offlen: Length of OFF string.
+ * @digi_onstr: Printer ON string.
+ * @digi_offstr: Printer OFF string.
+ * @digi_term: Terminal string.
+ */
 struct digi_t {
-	unsigned short	digi_flags;		/* Flags (see above) */
-	unsigned short	digi_maxcps;		/* Max printer CPS */
-	unsigned short	digi_maxchar;		/* Max chars in print queue */
-	unsigned short	digi_bufsize;		/* Buffer size */
-	unsigned char	digi_onlen;		/* Length of ON string */
-	unsigned char	digi_offlen;		/* Length of OFF string	*/
-	char		digi_onstr[DIGI_PLEN];	/* Printer on string */
-	char		digi_offstr[DIGI_PLEN];	/* Printer off string */
-	char		digi_term[DIGI_TSIZ];	/* terminal string */
+	unsigned short	digi_flags;
+	unsigned short	digi_maxcps;
+	unsigned short	digi_maxchar;
+	unsigned short	digi_bufsize;
+	unsigned char	digi_onlen;
+	unsigned char	digi_offlen;
+	char		digi_onstr[DIGI_PLEN];
+	char		digi_offstr[DIGI_PLEN];
+	char		digi_term[DIGI_TSIZ];
 };
 
-/* Structure to get driver status information */
-
+/**
+ * struct digi_dinfo - Driver status information.
+ * @dinfo_nboards: Number of boards configured.
+ * @dinfo_reserved: Not used, for future expansion.
+ * @dinfio_version: Driver version.
+ */
 struct digi_dinfo {
-	unsigned int	dinfo_nboards;		/* # boards configured */
-	char		dinfo_reserved[12];	/* for future expansion */
-	char		dinfo_version[16];	/* driver version */
+	unsigned int	dinfo_nboards;
+	char		dinfo_reserved[12];
+	char		dinfo_version[16];
 };
 
 #define	DIGI_GETDD	(('d' << 8) | 248)	/* get driver info */
 
-/*
- * Structure used with ioctl commands for per-board information
+/**
+ * struct digi_info - Ioctl commands for per board information.
  *
- * physsize and memsize differ when board has "windowed" memory
+ * Physsize and memsize differ when board has "windowed" memory.
+ *
+ * @info_bdnum: Board number (0 based).
+ * @info_ioport: IO port address.
+ * @indo_physaddr: Memory address.
+ * @info_physize: Size of host memory window.
+ * @info_memsize: Amount of dual-port memory on board.
+ * @info_bdtype: Board type.
+ * @info_nports: Number of ports.
+ * @info_bdstate: Board state.
+ * @info_reserved: Not used, for future expansion.
  */
 struct digi_info {
-	unsigned int	info_bdnum;		/* Board number (0 based) */
-	unsigned int	info_ioport;		/* io port address */
-	unsigned int	info_physaddr;		/* memory address */
-	unsigned int	info_physsize;		/* Size of host mem window */
-	unsigned int	info_memsize;		/* Amount of dual-port mem */
-						/* on board */
-	unsigned short	info_bdtype;		/* Board type */
-	unsigned short	info_nports;		/* number of ports */
-	char		info_bdstate;		/* board state */
-	char		info_reserved[7];	/* for future expansion */
+	unsigned int	info_bdnum;
+	unsigned int	info_ioport;
+	unsigned int	info_physaddr;
+	unsigned int	info_physsize;
+	unsigned int	info_memsize;
+	unsigned short	info_bdtype;
+	unsigned short	info_nports;
+	char		info_bdstate;
+	char		info_reserved[7];
 };
 
 #define	DIGI_GETBD	(('d' << 8) | 249)	/* get board info */
 
-struct digi_getbuffer /* Struct for holding buffer use counts */
-{
+/**
+ * struct digi_getbuffer - Holds buffer use counts.
+ */
+struct digi_getbuffer {
 	unsigned long tx_in;
 	unsigned long tx_out;
 	unsigned long rxbuf;
@@ -115,14 +141,24 @@ struct digi_getbuffer /* Struct for holding buffer use counts */
 	unsigned long txdone;
 };
 
+/**
+ * struct digi_getcounter
+ * @norun: Number of UART overrun errors.
+ * @noflow: Number of buffer overflow errors.
+ * @nframe: Number of framing errors.
+ * @nparity: Number of parity errors.
+ * @nbreak: Number of breaks received.
+ * @rbytes: Number of received bytes.
+ * @tbytes: Number of transmitted bytes.
+ */
 struct digi_getcounter {
-	unsigned long norun;		/* number of UART overrun errors */
-	unsigned long noflow;		/* number of buffer overflow errors */
-	unsigned long nframe;		/* number of framing errors */
-	unsigned long nparity;		/* number of parity errors */
-	unsigned long nbreak;		/* number of breaks received */
-	unsigned long rbytes;		/* number of received bytes */
-	unsigned long tbytes;		/* number of bytes transmitted fully */
+	unsigned long norun;
+	unsigned long noflow;
+	unsigned long nframe;
+	unsigned long nparity;
+	unsigned long nbreak;
+	unsigned long rbytes;
+	unsigned long tbytes;
 };
 
 /* Board State Definitions */
@@ -137,15 +173,14 @@ struct digi_getcounter {
 #define DIGI_REALPORT_GETCOUNTERS (('e' << 8) | 110)
 #define DIGI_REALPORT_GETEVENTS (('e' << 8) | 111)
 
-#define EV_OPU 0x0001 /* !<Output paused by client */
-#define EV_OPS 0x0002 /* !<Output paused by regular sw flowctrl */
-#define EV_IPU 0x0010 /* !<Input paused unconditionally by user */
-#define EV_IPS 0x0020 /* !<Input paused by high/low water marks */
-#define EV_TXB 0x0040 /* !<Transmit break pending */
+#define EV_OPU 0x0001 /* Output paused by client */
+#define EV_OPS 0x0002 /* Output paused by regular sw flowctrl */
+#define EV_IPU 0x0010 /* Input paused unconditionally by user */
+#define EV_IPS 0x0020 /* Input paused by high/low water marks */
+#define EV_TXB 0x0040 /* Transmit break pending */
 
-/*
- * This structure holds data needed for the intelligent <--> nonintelligent
- * DPA translation
+/**
+ * struct ni_info - intelligent <--> non-intelligent DPA translation.
  */
 struct ni_info {
 	int board;