[libata] polish DocBook docs a bit

Mainly involved fixing a great many docproc warnings, by filling in
missing documentation in the source code.

Documentation/DocBook/libata.tmpl

@@ -64,12 +64,16 @@
   <chapter id="libataExt">
      <title>libata Library</title>
 !Edrivers/scsi/libata-core.c
-!Edrivers/scsi/libata-scsi.c
   </chapter>
 
   <chapter id="libataInt">
-     <title>libata Internals</title>
+     <title>libata Core Internals</title>
 !Idrivers/scsi/libata-core.c
+  </chapter>
+
+  <chapter id="libataScsiInt">
+     <title>libata SCSI translation/emulation</title>
+!Edrivers/scsi/libata-scsi.c
 !Idrivers/scsi/libata-scsi.c
   </chapter>
 
@@ -83,9 +87,4 @@
 !Idrivers/scsi/sata_sil.c
   </chapter>
 
-  <chapter id="VIAInt">
-     <title>ata_via Internals</title>
-!Idrivers/scsi/sata_via.c
-  </chapter>
-
 </book>

drivers/scsi/ata_piix.c

@@ -272,7 +272,7 @@ static void piix_pata_phy_reset(struct ata_port *ap)
 
 /**
  *	piix_sata_probe - Probe PCI device for present SATA devices
- *	@pdev: PCI device to probe
+ *	@ap: Port associated with the PCI device we wish to probe
  *
  *	Reads SATA PCI device's PCI config register Port Configuration
  *	and Status (PCS) to determine port and device availability.

drivers/scsi/libata-core.c

@@ -115,7 +115,7 @@ static void msleep(unsigned long msecs)
 
 /**
  *	ata_tf_load_pio - send taskfile registers to host controller
- *	@ioaddr: set of IO ports to which output is sent
+ *	@ap: Port to which output is sent
  *	@tf: ATA taskfile register set
  *
  *	Outputs ATA taskfile to standard ATA host controller using PIO.
@@ -173,7 +173,7 @@ void ata_tf_load_pio(struct ata_port *ap, struct ata_taskfile *tf)
 
 /**
  *	ata_tf_load_mmio - send taskfile registers to host controller
- *	@ioaddr: set of IO ports to which output is sent
+ *	@ap: Port to which output is sent
  *	@tf: ATA taskfile register set
  *
  *	Outputs ATA taskfile to standard ATA host controller using MMIO.
@@ -333,7 +333,7 @@ void ata_tf_to_host_nolock(struct ata_port *ap, struct ata_taskfile *tf)
 
 /**
  *	ata_tf_read_pio - input device's ATA taskfile shadow registers
- *	@ioaddr: set of IO ports from which input is read
+ *	@ap: Port from which input is read
  *	@tf: ATA taskfile register set for storing input
  *
  *	Reads ATA taskfile registers for currently-selected device
@@ -365,7 +365,7 @@ void ata_tf_read_pio(struct ata_port *ap, struct ata_taskfile *tf)
 
 /**
  *	ata_tf_read_mmio - input device's ATA taskfile shadow registers
- *	@ioaddr: set of IO ports from which input is read
+ *	@ap: Port from which input is read
  *	@tf: ATA taskfile register set for storing input
  *
  *	Reads ATA taskfile registers for currently-selected device
@@ -431,6 +431,7 @@ u8 ata_check_status_mmio(struct ata_port *ap)
  *	ata_tf_to_fis - Convert ATA taskfile to SATA FIS structure
  *	@tf: Taskfile to convert
  *	@fis: Buffer into which data will output
+ *	@pmp: Port multiplier port
  *
  *	Converts a standard ATA taskfile to a Serial ATA
  *	FIS structure (Register - Host to Device).
@@ -1697,9 +1698,9 @@ static void ata_host_set_udma(struct ata_port *ap)
 }
 
 /**
- *	ata_dev_set_xfermode -
- *	@ap:
- *	@dev:
+ *	ata_dev_set_xfermode - Issue SET FEATURES - XFER MODE command
+ *	@ap: Port associated with device @dev
+ *	@dev: Device to which command will be sent
  *
  *	LOCKING:
  */
@@ -1738,9 +1739,9 @@ static void ata_dev_set_xfermode(struct ata_port *ap, struct ata_device *dev)
 }
 
 /**
- *	ata_dev_set_udma -
- *	@ap:
- *	@device:
+ *	ata_dev_set_udma - Set ATA device's transfer mode to Ultra DMA
+ *	@ap: Port associated with device @dev
+ *	@device: Device whose mode will be set
  *
  *	LOCKING:
  */
@@ -1762,9 +1763,9 @@ static void ata_dev_set_udma(struct ata_port *ap, unsigned int device)
 }
 
 /**
- *	ata_dev_set_pio -
- *	@ap:
- *	@device:
+ *	ata_dev_set_pio - Set ATA device's transfer mode to PIO
+ *	@ap: Port associated with device @dev
+ *	@device: Device whose mode will be set
  *
  *	LOCKING:
  */
@@ -2240,9 +2241,9 @@ void ata_eng_timeout(struct ata_port *ap)
 }
 
 /**
- *	ata_qc_new -
- *	@ap:
- *	@dev:
+ *	ata_qc_new - Request an available ATA command, for queueing
+ *	@ap: Port associated with device @dev
+ *	@dev: Device from whom we request an available command structure
  *
  *	LOCKING:
  */
@@ -2265,9 +2266,9 @@ static struct ata_queued_cmd *ata_qc_new(struct ata_port *ap)
 }
 
 /**
- *	ata_qc_new_init -
- *	@ap:
- *	@dev:
+ *	ata_qc_new_init - Request an available ATA command, and initialize it
+ *	@ap: Port associated with device @dev
+ *	@dev: Device from whom we request an available command structure
  *
  *	LOCKING:
  */
@@ -2299,9 +2300,9 @@ struct ata_queued_cmd *ata_qc_new_init(struct ata_port *ap,
 }
 
 /**
- *	ata_qc_complete -
- *	@qc:
- *	@drv_stat:
+ *	ata_qc_complete - Complete an active ATA command
+ *	@qc: Command to complete
+ *	@drv_stat: ATA status register contents
  *
  *	LOCKING:
  *
@@ -2568,9 +2569,9 @@ void ata_bmdma_start_pio (struct ata_queued_cmd *qc)
 }
 
 /**
- *	ata_dma_complete -
- *	@qc:
- *	@host_stat:
+ *	ata_dma_complete - Complete an active ATA BMDMA command
+ *	@qc: Command to complete
+ *	@host_stat: BMDMA status register contents
  *
  *	LOCKING:
  */
@@ -2687,10 +2688,10 @@ inline unsigned int ata_host_intr (struct ata_port *ap,
 }
 
 /**
- *	ata_interrupt -
- *	@irq:
- *	@dev_instance:
- *	@regs:
+ *	ata_interrupt - Default ATA host interrupt handler
+ *	@irq: irq line
+ *	@dev_instance: pointer to our host information structure
+ *	@regs: unused
  *
  *	LOCKING:
  *
@@ -2879,9 +2880,9 @@ static void ata_probe_task(void *_data)
 }
 
 /**
- *	ata_host_remove -
- *	@ap:
- *	@do_unregister:
+ *	ata_host_remove - Unregister SCSI host structure with upper layers
+ *	@ap: Port to unregister
+ *	@do_unregister: 1 if we fully unregister, 0 to just stop the port
  *
  *	LOCKING:
  */
@@ -2899,10 +2900,12 @@ static void ata_host_remove(struct ata_port *ap, unsigned int do_unregister)
 }
 
 /**
- *	ata_host_init -
- *	@host:
- *	@ent:
- *	@port_no:
+ *	ata_host_init - Initialize an ata_port structure
+ *	@ap: Structure to initialize
+ *	@host: associated SCSI mid-layer structure
+ *	@host_set: Collection of hosts to which @ap belongs
+ *	@ent: Probe information provided by low-level driver
+ *	@port_no: Port number associated with this ata_port
  *
  *	LOCKING:
  *
@@ -2956,10 +2959,10 @@ static void ata_host_init(struct ata_port *ap, struct Scsi_Host *host,
 }
 
 /**
- *	ata_host_add -
- *	@ent:
- *	@host_set:
- *	@port_no:
+ *	ata_host_add - Attach low-level ATA driver to system
+ *	@ent: Information provided by low-level driver
+ *	@host_set: Collections of ports to which we add
+ *	@port_no: Port number associated with this host
  *
  *	LOCKING:
  *
@@ -3115,7 +3118,7 @@ int ata_device_add(struct ata_probe_ent *ent)
  *	ata_scsi_release - SCSI layer callback hook for host unload
  *	@host: libata host to be unloaded
  *
- *	Performs all duties necessary to shut down a libata port:
+ *	Performs all duties necessary to shut down a libata port...
  *	Kill port kthread, disable port, and release resources.
  *
  *	LOCKING:
@@ -3140,7 +3143,7 @@ int ata_scsi_release(struct Scsi_Host *host)
 
 /**
  *	ata_std_ports - initialize ioaddr with standard port offsets.
- *	@ioaddr:
+ *	@ioaddr: IO address structure to be initialized
  */
 void ata_std_ports(struct ata_ioports *ioaddr)
 {
@@ -3157,10 +3160,10 @@ void ata_std_ports(struct ata_ioports *ioaddr)
 }
 
 /**
- *	ata_pci_init_one -
- *	@pdev:
- *	@port_info:
- *	@n_ports:
+ *	ata_pci_init_one - Initialize/register PCI IDE host controller
+ *	@pdev: Controller to be initialized
+ *	@port_info: Information from low-level host driver
+ *	@n_ports: Number of ports attached to host controller
  *
  *	LOCKING:
  *	Inherited from PCI layer (may sleep).

drivers/scsi/libata-scsi.c

@@ -340,6 +340,7 @@ static unsigned int ata_scsi_rw_xlat(struct ata_queued_cmd *qc, u8 *scsicmd)
  *	@dev: ATA device to which the command is addressed
  *	@cmd: SCSI command to execute
  *	@done: SCSI command completion function
+ *	@xlat_func: Actor which translates @cmd to an ATA taskfile
  *
  *	Our ->queuecommand() function has decided that the SCSI
  *	command issued can be directly translated into an ATA

drivers/scsi/sata_sil.c

@@ -267,7 +267,7 @@ static void sil_scr_write (struct ata_port *ap, unsigned int sc_reg, u32 val)
  *
  *	20040111 - Seagate drives affected by the Mod15Write bug are blacklisted
  *	The Maxtor quirk is in the blacklist, but I'm keeping the original
- *	pessimistic fix for the following reasons:
+ *	pessimistic fix for the following reasons...
  *	- There seems to be less info on it, only one device gleaned off the
  *	Windows	driver, maybe only one is affected.  More info would be greatly
  *	appreciated.

drivers/scsi/sata_via.c

@@ -148,17 +148,6 @@ static unsigned long svia_scr_addr(unsigned long addr, unsigned int port)
 	return addr + (port * 128);
 }
 
-/**
- *	svia_init_one -
- *	@pdev:
- *	@ent:
- *
- *	LOCKING:
- *
- *	RETURNS:
- *
- */
-
 static int svia_init_one (struct pci_dev *pdev, const struct pci_device_id *ent)
 {
 	static int printed_version;
@@ -289,27 +278,11 @@ static int svia_init_one (struct pci_dev *pdev, const struct pci_device_id *ent)
 	return rc;
 }
 
-/**
- *	svia_init -
- *
- *	LOCKING:
- *
- *	RETURNS:
- *
- */
-
 static int __init svia_init(void)
 {
 	return pci_module_init(&svia_pci_driver);
 }
 
-/**
- *	svia_exit -
- *
- *	LOCKING:
- *
- */
-
 static void __exit svia_exit(void)
 {
 	pci_unregister_driver(&svia_pci_driver);