[SCSI] megaraid: fix kernel-doc

kernel-doc modifications:
- change "@param var" notation to @var;
- change function/description separator from ':' to '-';
- change var/description separator from '-' to ':';
- fix a few doc. typos;
- don't use kernel-doc /** lead-in when the doc. block is not kernel-doc;
- use Linux common */ ending comment format instead of **/;
- use correct function parameter names;
- place function parameters immediately after the function short description;
- place kernel-doc immediately before its function or macro;

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Acked-by: Sumant Patro <sumantp@lsil.com>
Signed-off-by: James Bottomley <James.Bottomley@SteelEye.com>

drivers/scsi/megaraid/mega_common.h

@@ -46,17 +46,17 @@
 
 /**
  * scb_t - scsi command control block
- * @param ccb		: command control block for individual driver
- * @param list		: list of control blocks
- * @param gp		: general purpose field for LLDs
- * @param sno		: all SCBs have a serial number
- * @param scp		: associated scsi command
- * @param state		: current state of scb
- * @param dma_dir	: direction of data transfer
- * @param dma_type	: transfer with sg list, buffer, or no data transfer
- * @param dev_channel	: actual channel on the device
- * @param dev_target	: actual target on the device
- * @param status	: completion status
+ * @ccb			: command control block for individual driver
+ * @list		: list of control blocks
+ * @gp			: general purpose field for LLDs
+ * @sno			: all SCBs have a serial number
+ * @scp			: associated scsi command
+ * @state		: current state of scb
+ * @dma_dir		: direction of data transfer
+ * @dma_type		: transfer with sg list, buffer, or no data transfer
+ * @dev_channel		: actual channel on the device
+ * @dev_target		: actual target on the device
+ * @status		: completion status
  *
  * This is our central data structure to issue commands the each driver.
  * Driver specific data structures are maintained in the ccb field.
@@ -99,42 +99,42 @@ typedef struct {
 
 /**
  * struct adapter_t - driver's initialization structure
- * @param dpc_h			: tasklet handle
- * @param pdev			: pci configuration pointer for kernel
- * @param host			: pointer to host structure of mid-layer
- * @param lock			: synchronization lock for mid-layer and driver
- * @param quiescent		: driver is quiescent for now.
- * @param outstanding_cmds	: number of commands pending in the driver
- * @param kscb_list		: pointer to the bulk of SCBs pointers for IO
- * @param kscb_pool		: pool of free scbs for IO
- * @param kscb_pool_lock	: lock for pool of free scbs
- * @param pend_list		: pending commands list
- * @param pend_list_lock	: exlusion lock for pending commands list
- * @param completed_list	: list of completed commands
- * @param completed_list_lock	: exclusion lock for list of completed commands
- * @param sglen			: max sg elements supported
- * @param device_ids		: to convert kernel device addr to our devices.
- * @param raid_device		: raid adapter specific pointer
- * @param max_channel		: maximum channel number supported - inclusive
- * @param max_target		: max target supported - inclusive
- * @param max_lun		: max lun supported - inclusive
- * @param unique_id		: unique identifier for each adapter
- * @param irq			: IRQ for this adapter
- * @param ito			: internal timeout value, (-1) means no timeout
- * @param ibuf			: buffer to issue internal commands
- * @param ibuf_dma_h		: dma handle for the above buffer
- * @param uscb_list		: SCB pointers for user cmds, common mgmt module
- * @param uscb_pool		: pool of SCBs for user commands
- * @param uscb_pool_lock	: exclusion lock for these SCBs
- * @param max_cmds		: max outstanding commands
- * @param fw_version		: firmware version
- * @param bios_version		: bios version
- * @param max_cdb_sz		: biggest CDB size supported.
- * @param ha			: is high availability present - clustering
- * @param init_id		: initiator ID, the default value should be 7
- * @param max_sectors		: max sectors per request
- * @param cmd_per_lun		: max outstanding commands per LUN
- * @param being_detached	: set when unloading, no more mgmt calls
+ * @aram dpc_h			: tasklet handle
+ * @pdev			: pci configuration pointer for kernel
+ * @host			: pointer to host structure of mid-layer
+ * @lock			: synchronization lock for mid-layer and driver
+ * @quiescent			: driver is quiescent for now.
+ * @outstanding_cmds		: number of commands pending in the driver
+ * @kscb_list			: pointer to the bulk of SCBs pointers for IO
+ * @kscb_pool			: pool of free scbs for IO
+ * @kscb_pool_lock		: lock for pool of free scbs
+ * @pend_list			: pending commands list
+ * @pend_list_lock		: exclusion lock for pending commands list
+ * @completed_list		: list of completed commands
+ * @completed_list_lock		: exclusion lock for list of completed commands
+ * @sglen			: max sg elements supported
+ * @device_ids			: to convert kernel device addr to our devices.
+ * @raid_device			: raid adapter specific pointer
+ * @max_channel			: maximum channel number supported - inclusive
+ * @max_target			: max target supported - inclusive
+ * @max_lun			: max lun supported - inclusive
+ * @unique_id			: unique identifier for each adapter
+ * @irq				: IRQ for this adapter
+ * @ito				: internal timeout value, (-1) means no timeout
+ * @ibuf			: buffer to issue internal commands
+ * @ibuf_dma_h			: dma handle for the above buffer
+ * @uscb_list			: SCB pointers for user cmds, common mgmt module
+ * @uscb_pool			: pool of SCBs for user commands
+ * @uscb_pool_lock		: exclusion lock for these SCBs
+ * @max_cmds			: max outstanding commands
+ * @fw_version			: firmware version
+ * @bios_version		: bios version
+ * @max_cdb_sz			: biggest CDB size supported.
+ * @ha				: is high availability present - clustering
+ * @init_id			: initiator ID, the default value should be 7
+ * @max_sectors			: max sectors per request
+ * @cmd_per_lun			: max outstanding commands per LUN
+ * @being_detached		: set when unloading, no more mgmt calls
  *
  *
  * mraid_setup_device_map() can be called anytime after the device map is
@@ -211,23 +211,23 @@ typedef struct {
 #define SCP2ADAPTER(scp)	(adapter_t *)SCSIHOST2ADAP(SCP2HOST(scp))
 
 
-/**
- * MRAID_GET_DEVICE_MAP - device ids
- * @param adp		- Adapter's soft state
- * @param scp		- mid-layer scsi command pointer
- * @param p_chan	- physical channel on the controller
- * @param target	- target id of the device or logical drive number
- * @param islogical	- set if the command is for the logical drive
- *
- * Macro to retrieve information about device class, logical or physical and
- * the corresponding physical channel and target or logical drive number
- **/
 #define MRAID_IS_LOGICAL(adp, scp)	\
 	(SCP2CHANNEL(scp) == (adp)->max_channel) ? 1 : 0
 
 #define MRAID_IS_LOGICAL_SDEV(adp, sdev)	\
 	(sdev->channel == (adp)->max_channel) ? 1 : 0
 
+/**
+ * MRAID_GET_DEVICE_MAP - device ids
+ * @adp			: adapter's soft state
+ * @scp			: mid-layer scsi command pointer
+ * @p_chan		: physical channel on the controller
+ * @target		: target id of the device or logical drive number
+ * @islogical		: set if the command is for the logical drive
+ *
+ * Macro to retrieve information about device class, logical or physical and
+ * the corresponding physical channel and target or logical drive number
+ */
 #define MRAID_GET_DEVICE_MAP(adp, scp, p_chan, target, islogical)	\
 	/*								\
 	 * Is the request coming for the virtual channel		\
@@ -273,8 +273,8 @@ typedef struct {
 
 /*
  * struct mraid_pci_blk - structure holds DMA memory block info
- * @param vaddr		: virtual address to a memory block
- * @param dma_addr	: DMA handle to a memory block
+ * @vaddr		: virtual address to a memory block
+ * @dma_addr		: DMA handle to a memory block
  *
  * This structure is filled up for the caller. It is the responsibilty of the
  * caller to allocate this array big enough to store addresses for all

drivers/scsi/megaraid/megaraid_ioctl.h

@@ -22,23 +22,23 @@
 
 #include "mbox_defs.h"
 
-/**
- * con_log() - console log routine
- * @param level		: indicates the severity of the message.
- * @fparam mt		: format string
- *
- * con_log displays the error messages on the console based on the current
- * debug level. Also it attaches the appropriate kernel severity level with
- * the message.
- *
- *
- * consolge messages debug levels
+/*
+ * console messages debug levels
  */
 #define	CL_ANN		0	/* print unconditionally, announcements */
 #define CL_DLEVEL1	1	/* debug level 1, informative */
 #define CL_DLEVEL2	2	/* debug level 2, verbose */
 #define CL_DLEVEL3	3	/* debug level 3, very verbose */
 
+/**
+ * con_log() - console log routine
+ * @level		: indicates the severity of the message.
+ * @fmt			: format string
+ *
+ * con_log displays the error messages on the console based on the current
+ * debug level. Also it attaches the appropriate kernel severity level with
+ * the message.
+ */
 #define	con_log(level, fmt) if (LSI_DBGLVL >= level) printk fmt;
 
 /*
@@ -157,14 +157,14 @@ typedef struct uioc {
 /**
  * struct mraid_hba_info - information about the controller
  *
- * @param pci_vendor_id		: PCI vendor id
- * @param pci_device_id		: PCI device id
- * @param subsystem_vendor_id	: PCI subsystem vendor id
- * @param subsystem_device_id	: PCI subsystem device id
- * @param baseport		: base port of hba memory
- * @param pci_bus		: PCI bus
- * @param pci_dev_fn		: PCI device/function values
- * @param irq			: interrupt vector for the device
+ * @pci_vendor_id		: PCI vendor id
+ * @pci_device_id		: PCI device id
+ * @subsystem_vendor_id		: PCI subsystem vendor id
+ * @subsystem_device_id		: PCI subsystem device id
+ * @baseport			: base port of hba memory
+ * @pci_bus			: PCI bus
+ * @pci_dev_fn			: PCI device/function values
+ * @irq				: interrupt vector for the device
  *
  * Extended information of 256 bytes about the controller. Align on the single
  * byte boundary so that 32-bit applications can be run on 64-bit platform

drivers/scsi/megaraid/megaraid_mbox.h

@@ -146,27 +146,27 @@ typedef struct {
 
 /**
  * mraid_device_t - adapter soft state structure for mailbox controllers
- * @param una_mbox64		: 64-bit mbox - unaligned
- * @param una_mbox64_dma	: mbox dma addr - unaligned
- * @param mbox			: 32-bit mbox - aligned
- * @param mbox64		: 64-bit mbox - aligned
- * @param mbox_dma		: mbox dma addr - aligned
- * @param mailbox_lock		: exclusion lock for the mailbox
- * @param baseport		: base port of hba memory
- * @param baseaddr		: mapped addr of hba memory
- * @param mbox_pool		: pool of mailboxes
- * @param mbox_pool_handle	: handle for the mailbox pool memory
- * @param epthru_pool		: a pool for extended passthru commands
- * @param epthru_pool_handle	: handle to the pool above
- * @param sg_pool		: pool of scatter-gather lists for this driver
- * @param sg_pool_handle	: handle to the pool above
- * @param ccb_list		: list of our command control blocks
- * @param uccb_list		: list of cmd control blocks for mgmt module
- * @param umbox64		: array of mailbox for user commands (cmm)
- * @param pdrv_state		: array for state of each physical drive.
- * @param last_disp		: flag used to show device scanning
- * @param hw_error		: set if FW not responding
- * @param fast_load		: If set, skip physical device scanning
+ * @una_mbox64			: 64-bit mbox - unaligned
+ * @una_mbox64_dma		: mbox dma addr - unaligned
+ * @mbox			: 32-bit mbox - aligned
+ * @mbox64			: 64-bit mbox - aligned
+ * @mbox_dma			: mbox dma addr - aligned
+ * @mailbox_lock		: exclusion lock for the mailbox
+ * @baseport			: base port of hba memory
+ * @baseaddr			: mapped addr of hba memory
+ * @mbox_pool			: pool of mailboxes
+ * @mbox_pool_handle		: handle for the mailbox pool memory
+ * @epthru_pool			: a pool for extended passthru commands
+ * @epthru_pool_handle		: handle to the pool above
+ * @sg_pool			: pool of scatter-gather lists for this driver
+ * @sg_pool_handle		: handle to the pool above
+ * @ccb_list			: list of our command control blocks
+ * @uccb_list			: list of cmd control blocks for mgmt module
+ * @umbox64			: array of mailbox for user commands (cmm)
+ * @pdrv_state			: array for state of each physical drive.
+ * @last_disp			: flag used to show device scanning
+ * @hw_error			: set if FW not responding
+ * @fast_load			: If set, skip physical device scanning
  * @channel_class		: channel class, RAID or SCSI
  * @sysfs_sem			: semaphore to serialize access to sysfs res.
  * @sysfs_uioc			: management packet to issue FW calls from sysfs

drivers/scsi/megaraid/megaraid_mm.c

@@ -78,10 +78,10 @@ static struct file_operations lsi_fops = {
 
 /**
  * mraid_mm_open - open routine for char node interface
- * @inod	: unused
+ * @inode	: unused
  * @filep	: unused
  *
- * allow ioctl operations by apps only if they superuser privilege
+ * Allow ioctl operations by apps only if they have superuser privilege.
  */
 static int
 mraid_mm_open(struct inode *inode, struct file *filep)
@@ -214,7 +214,9 @@ mraid_mm_ioctl(struct inode *inode, struct file *filep, unsigned int cmd,
 /**
  * mraid_mm_get_adapter - Returns corresponding adapters for the mimd packet
  * @umimd	: User space mimd_t ioctl packet
- * @adapter	: pointer to the adapter (OUT)
+ * @rval	: returned success/error status
+ *
+ * The function return value is a pointer to the located @adapter.
  */
 static mraid_mmadp_t *
 mraid_mm_get_adapter(mimd_t __user *umimd, int *rval)
@@ -252,11 +254,11 @@ mraid_mm_get_adapter(mimd_t __user *umimd, int *rval)
 	return adapter;
 }
 
-/*
- * handle_drvrcmd - This routine checks if the opcode is a driver
- * 			  cmd and if it is, handles it.
+/**
+ * handle_drvrcmd - Checks if the opcode is a driver cmd and if it is, handles it.
  * @arg		: packet sent by the user app
  * @old_ioctl	: mimd if 1; uioc otherwise
+ * @rval	: pointer for command's returned value (not function status)
  */
 static int
 handle_drvrcmd(void __user *arg, uint8_t old_ioctl, int *rval)
@@ -322,8 +324,8 @@ old_packet:
 
 /**
  * mimd_to_kioc	- Converter from old to new ioctl format
- *
  * @umimd	: user space old MIMD IOCTL
+ * @adp		: adapter softstate
  * @kioc	: kernel space new format IOCTL
  *
  * Routine to convert MIMD interface IOCTL to new interface IOCTL packet. The
@@ -474,7 +476,6 @@ mimd_to_kioc(mimd_t __user *umimd, mraid_mmadp_t *adp, uioc_t *kioc)
 
 /**
  * mraid_mm_attch_buf - Attach a free dma buffer for required size
- *
  * @adp		: Adapter softstate
  * @kioc	: kioc that the buffer needs to be attached to
  * @xferlen	: required length for buffer
@@ -607,7 +608,6 @@ mraid_mm_alloc_kioc(mraid_mmadp_t *adp)
 
 /**
  * mraid_mm_dealloc_kioc - Return kioc to free pool
- *
  * @adp		: Adapter softstate
  * @kioc	: uioc_t node to be returned to free pool
  */
@@ -652,7 +652,6 @@ mraid_mm_dealloc_kioc(mraid_mmadp_t *adp, uioc_t *kioc)
 
 /**
  * lld_ioctl - Routine to issue ioctl to low level drvr
- *
  * @adp		: The adapter handle
  * @kioc	: The ioctl packet with kernel addresses
  */
@@ -705,7 +704,6 @@ lld_ioctl(mraid_mmadp_t *adp, uioc_t *kioc)
 
 /**
  * ioctl_done - callback from the low level driver
- *
  * @kioc	: completed ioctl packet
  */
 static void
@@ -756,9 +754,8 @@ ioctl_done(uioc_t *kioc)
 }
 
 
-/*
- * lld_timedout	: callback from the expired timer
- *
+/**
+ * lld_timedout	- callback from the expired timer
  * @ptr		: ioctl packet that timed out
  */
 static void
@@ -776,8 +773,7 @@ lld_timedout(unsigned long ptr)
 
 
 /**
- * kioc_to_mimd	: Converter from new back to old format
- *
+ * kioc_to_mimd	- Converter from new back to old format
  * @kioc	: Kernel space IOCTL packet (successfully issued)
  * @mimd	: User space MIMD packet
  */
@@ -855,7 +851,6 @@ kioc_to_mimd(uioc_t *kioc, mimd_t __user *mimd)
 
 /**
  * hinfo_to_cinfo - Convert new format hba info into old format
- *
  * @hinfo	: New format, more comprehensive adapter info
  * @cinfo	: Old format adapter info to support mimd_t apps
  */
@@ -878,10 +873,9 @@ hinfo_to_cinfo(mraid_hba_info_t *hinfo, mcontroller_t *cinfo)
 }
 
 
-/*
- * mraid_mm_register_adp - Registration routine for low level drvrs
- *
- * @adp	: Adapter objejct
+/**
+ * mraid_mm_register_adp - Registration routine for low level drivers
+ * @lld_adp	: Adapter objejct
  */
 int
 mraid_mm_register_adp(mraid_mmadp_t *lld_adp)
@@ -1007,15 +1001,14 @@ memalloc_error:
 
 /**
  * mraid_mm_adapter_app_handle - return the application handle for this adapter
+ * @unique_id	: adapter unique identifier
  *
- * For the given driver data, locate the adadpter in our global list and
+ * For the given driver data, locate the adapter in our global list and
  * return the corresponding handle, which is also used by applications to
  * uniquely identify an adapter.
  *
- * @param unique_id : adapter unique identifier
- *
- * @return adapter handle if found in the list
- * @return 0 if adapter could not be located, should never happen though
+ * Return adapter handle if found in the list.
+ * Return 0 if adapter could not be located, should never happen though.
  */
 uint32_t
 mraid_mm_adapter_app_handle(uint32_t unique_id)
@@ -1040,7 +1033,6 @@ mraid_mm_adapter_app_handle(uint32_t unique_id)
 
 /**
  * mraid_mm_setup_dma_pools - Set up dma buffer pools per adapter
- *
  * @adp	: Adapter softstate
  *
  * We maintain a pool of dma buffers per each adapter. Each pool has one
@@ -1093,11 +1085,11 @@ dma_pool_setup_error:
 }
 
 
-/*
+/**
  * mraid_mm_unregister_adp - Unregister routine for low level drivers
- *				  Assume no outstanding ioctls to llds.
- *
  * @unique_id	: UID of the adpater
+ *
+ * Assumes no outstanding ioctls to llds.
  */
 int
 mraid_mm_unregister_adp(uint32_t unique_id)
@@ -1131,7 +1123,6 @@ mraid_mm_unregister_adp(uint32_t unique_id)
 
 /**
  * mraid_mm_free_adp_resources - Free adapter softstate
- *
  * @adp	: Adapter softstate
  */
 static void
@@ -1162,7 +1153,6 @@ mraid_mm_free_adp_resources(mraid_mmadp_t *adp)
 
 /**
  * mraid_mm_teardown_dma_pools - Free all per adapter dma buffers
- *
  * @adp	: Adapter softstate
  */
 static void
@@ -1190,7 +1180,7 @@ mraid_mm_teardown_dma_pools(mraid_mmadp_t *adp)
 }
 
 /**
- * mraid_mm_init	: Module entry point
+ * mraid_mm_init	- Module entry point
  */
 static int __init
 mraid_mm_init(void)
@@ -1214,10 +1204,13 @@ mraid_mm_init(void)
 }
 
 
-/**
- * mraid_mm_compat_ioctl	: 32bit to 64bit ioctl conversion routine
- */
 #ifdef CONFIG_COMPAT
+/**
+ * mraid_mm_compat_ioctl	- 32bit to 64bit ioctl conversion routine
+ * @filep	: file operations pointer (ignored)
+ * @cmd		: ioctl command
+ * @arg		: user ioctl packet
+ */
 static long
 mraid_mm_compat_ioctl(struct file *filep, unsigned int cmd,
 		      unsigned long arg)
@@ -1231,7 +1224,7 @@ mraid_mm_compat_ioctl(struct file *filep, unsigned int cmd,
 #endif
 
 /**
- * mraid_mm_exit	: Module exit point
+ * mraid_mm_exit	- Module exit point
  */
 static void __exit
 mraid_mm_exit(void)

drivers/scsi/megaraid/megaraid_sas.h

@@ -15,7 +15,7 @@
 #ifndef LSI_MEGARAID_SAS_H
 #define LSI_MEGARAID_SAS_H
 
-/**
+/*
  * MegaRAID SAS Driver meta data
  */
 #define MEGASAS_VERSION				"00.00.03.05"
@@ -40,7 +40,7 @@
  * "message frames"
  */
 
-/**
+/*
  * FW posts its state in upper 4 bits of outbound_msg_0 register
  */
 #define MFI_STATE_MASK				0xF0000000
@@ -58,7 +58,7 @@
 
 #define MEGAMFI_FRAME_SIZE			64
 
-/**
+/*
  * During FW init, clear pending cmds & reset state using inbound_msg_0
  *
  * ABORT	: Abort all pending cmds
@@ -78,7 +78,7 @@
 						MFI_INIT_MFIMODE| \
 						MFI_INIT_ABORT
 
-/**
+/*
  * MFI frame flags
  */
 #define MFI_FRAME_POST_IN_REPLY_QUEUE		0x0000
@@ -92,12 +92,12 @@
 #define MFI_FRAME_DIR_READ			0x0010
 #define MFI_FRAME_DIR_BOTH			0x0018
 
-/**
+/*
  * Definition for cmd_status
  */
 #define MFI_CMD_STATUS_POLL_MODE		0xFF
 
-/**
+/*
  * MFI command opcodes
  */
 #define MFI_CMD_INIT				0x00
@@ -128,7 +128,7 @@
 #define MR_DCMD_CLUSTER_RESET_ALL		0x08010100
 #define MR_DCMD_CLUSTER_RESET_LD		0x08010200
 
-/**
+/*
  * MFI command completion codes
  */
 enum MFI_STAT {