[SCSI] Add Documentation and integrate into docbook build

Add Documentation/DocBook/scsi_midlayer.tmpl, add to Makefile, and update
lots of kerneldoc comments in drivers/scsi/*.

Updated with comments from Stefan Richter, Stephen M. Cameron,
 James Bottomley and Randy Dunlap.

Signed-off-by: Rob Landley <rob@landley.net>
Signed-off-by: James Bottomley <James.Bottomley@HansenPartnership.com>

1 files changed, 20 insertions, 22 deletions

diff --git a/drivers/scsi/scsi_lib.c b/drivers/scsi/scsi_lib.c
index a9ac5b1b1667..199b02452259 100644
--- a/drivers/scsi/scsi_lib.c
+++ b/drivers/scsi/scsi_lib.c
@@ -175,7 +175,7 @@ int scsi_queue_insert(struct scsi_cmnd *cmd, int reason)
  *
  * returns the req->errors value which is the scsi_cmnd result
  * field.
- **/
+ */
 int scsi_execute(struct scsi_device *sdev, const unsigned char *cmd,
                  int data_direction, void *buffer, unsigned bufflen,
                  unsigned char *sense, int timeout, int retries, int flags)
@@ -274,7 +274,7 @@ static void scsi_bi_endio(struct bio *bio, int error)
 /**
  * scsi_req_map_sg - map a scatterlist into a request
  * @rq:         request to fill
- * @sg:         scatterlist
+ * @sgl:        scatterlist
  * @nsegs:      number of elements
  * @bufflen:    len of buffer
  * @gfp:        memory allocation flags
@@ -365,14 +365,16 @@ free_bios:
  * @sdev:       scsi device
  * @cmd:        scsi command
  * @cmd_len:    length of scsi cdb
- * @data_direction: data direction
+ * @data_direction: DMA_TO_DEVICE, DMA_FROM_DEVICE, or DMA_NONE
  * @buffer:     data buffer (this can be a kernel buffer or scatterlist)
  * @bufflen:    len of buffer
  * @use_sg:     if buffer is a scatterlist this is the number of elements
  * @timeout:    request timeout in seconds
  * @retries:    number of times to retry request
- * @flags:      or into request flags
- **/
+ * @privdata:   data passed to done()
+ * @done:       callback function when done
+ * @gfp:        memory allocation flags
+ */
 int scsi_execute_async(struct scsi_device *sdev, const unsigned char *cmd,
                        int cmd_len, int data_direction, void *buffer, unsigned bufflen,
                        int use_sg, int timeout, int retries, void *privdata,
@@ -1804,7 +1806,7 @@ void scsi_exit_queue(void)
  *      @timeout: command timeout
  *      @retries: number of retries before failing
  *      @data: returns a structure abstracting the mode header data
- *      @sense: place to put sense data (or NULL if no sense to be collected).
+ *      @sshdr: place to put sense data (or NULL if no sense to be collected).
  *              must be SCSI_SENSE_BUFFERSIZE big.
  *
  *      Returns zero if successful; negative error number or scsi
@@ -1871,8 +1873,7 @@ scsi_mode_select(struct scsi_device *sdev, int pf, int sp, int modepage,
 EXPORT_SYMBOL_GPL(scsi_mode_select);
 
 /**
- *      scsi_mode_sense - issue a mode sense, falling back from 10 to 
- *              six bytes if necessary.
+ *      scsi_mode_sense - issue a mode sense, falling back from 10 to six bytes if necessary.
  *      @sdev:  SCSI device to be queried
  *      @dbd:   set if mode sense will allow block descriptors to be returned
  *      @modepage: mode page being requested
@@ -1881,13 +1882,13 @@ EXPORT_SYMBOL_GPL(scsi_mode_select);
  *      @timeout: command timeout
  *      @retries: number of retries before failing
  *      @data: returns a structure abstracting the mode header data
- *      @sense: place to put sense data (or NULL if no sense to be collected).
+ *      @sshdr: place to put sense data (or NULL if no sense to be collected).
  *              must be SCSI_SENSE_BUFFERSIZE big.
  *
  *      Returns zero if unsuccessful, or the header offset (either 4
  *      or 8 depending on whether a six or ten byte command was
  *      issued) if successful.
- **/
+ */
 int
 scsi_mode_sense(struct scsi_device *sdev, int dbd, int modepage,
                   unsigned char *buffer, int len, int timeout, int retries,
@@ -2007,14 +2008,13 @@ scsi_test_unit_ready(struct scsi_device *sdev, int timeout, int retries)
 EXPORT_SYMBOL(scsi_test_unit_ready);
 
 /**
- *      scsi_device_set_state - Take the given device through the device
- *              state model.
+ *      scsi_device_set_state - Take the given device through the device state model.
  *      @sdev:  scsi device to change the state of.
  *      @state: state to change to.
  *
  *      Returns zero if unsuccessful or an error if the requested 
  *      transition is illegal.
- **/
+ */
 int
 scsi_device_set_state(struct scsi_device *sdev, enum scsi_device_state state)
 {
@@ -2264,7 +2264,7 @@ EXPORT_SYMBOL_GPL(sdev_evt_send_simple);
  *      Must be called with user context, may sleep.
  *
  *      Returns zero if unsuccessful or an error if not.
- **/
+ */
 int
 scsi_device_quiesce(struct scsi_device *sdev)
 {
@@ -2289,7 +2289,7 @@ EXPORT_SYMBOL(scsi_device_quiesce);
  *      queues.
  *
  *      Must be called with user context, may sleep.
- **/
+ */
 void
 scsi_device_resume(struct scsi_device *sdev)
 {
@@ -2326,8 +2326,7 @@ scsi_target_resume(struct scsi_target *starget)
 EXPORT_SYMBOL(scsi_target_resume);
 
 /**
- * scsi_internal_device_block - internal function to put a device
- *                              temporarily into the SDEV_BLOCK state
+ * scsi_internal_device_block - internal function to put a device temporarily into the SDEV_BLOCK state
  * @sdev:       device to block
  *
  * Block request made by scsi lld's to temporarily stop all
@@ -2342,7 +2341,7 @@ EXPORT_SYMBOL(scsi_target_resume);
  *      state, all commands are deferred until the scsi lld reenables
  *      the device with scsi_device_unblock or device_block_tmo fires.
  *      This routine assumes the host_lock is held on entry.
- **/
+ */
 int
 scsi_internal_device_block(struct scsi_device *sdev)
 {
@@ -2382,7 +2381,7 @@ EXPORT_SYMBOL_GPL(scsi_internal_device_block);
  *      (which must be a legal transition) allowing the midlayer to
  *      goose the queue for this device.  This routine assumes the 
  *      host_lock is held upon entry.
- **/
+ */
 int
 scsi_internal_device_unblock(struct scsi_device *sdev)
 {
@@ -2460,7 +2459,7 @@ EXPORT_SYMBOL_GPL(scsi_target_unblock);
 
 /**
  * scsi_kmap_atomic_sg - find and atomically map an sg-elemnt
- * @sg:         scatter-gather list
+ * @sgl:        scatter-gather list
  * @sg_count:   number of segments in sg
  * @offset:     offset in bytes into sg, on return offset into the mapped area
  * @len:        bytes to map, on return number of bytes mapped
@@ -2509,8 +2508,7 @@ void *scsi_kmap_atomic_sg(struct scatterlist *sgl, int sg_count,
 EXPORT_SYMBOL(scsi_kmap_atomic_sg);
 
 /**
- * scsi_kunmap_atomic_sg - atomically unmap a virtual address, previously
- *                         mapped with scsi_kmap_atomic_sg
+ * scsi_kunmap_atomic_sg - atomically unmap a virtual address, previously mapped with scsi_kmap_atomic_sg
  * @virt:       virtual address to be unmapped
  */
 void scsi_kunmap_atomic_sg(void *virt)