[PATCH] kernel documentation fixes

From: Michael Still <mikal@stillhq.com>

The patch squelches build errors in the kernel-doc make targets by adding
documentation to arguements previously not documented, and updating the
argument names where they have changed.

diff --git a/arch/i386/kernel/mca.c b/arch/i386/kernel/mca.c
index 7ecca527cd5403ba59148646829e1f738057527a..57d118e4d6e58eeb600379c1c6ad15e1113136a6 100644 (file)
--- a/arch/i386/kernel/mca.c
+++ b/arch/i386/kernel/mca.c
@@ -132,7 +132,9 @@ struct resource mca_standard_resources[] = {
 #define MCA_STANDARD_RESOURCES (sizeof(mca_standard_resources)/sizeof(struct resource))
 
 /**
- *     mca_read_pos - read the POS registers into a memory buffer
+ *     mca_read_and_store_pos - read the POS registers into a memory buffer
+ *      @pos: a char pointer to 8 bytes, contains the POS register value on
+ *            successful return
  *
  *     Returns 1 if a card actually exists (i.e. the pos isn't
  *     all 0xff) or 0 otherwise

diff --git a/drivers/block/ll_rw_blk.c b/drivers/block/ll_rw_blk.c
index 0e71b28f621cbf762d524439c429413f65b26b37..473121c6b686ee7c75dd3d6d3cb42b7334c68c32 100644 (file)
--- a/drivers/block/ll_rw_blk.c
+++ b/drivers/block/ll_rw_blk.c
@@ -119,7 +119,7 @@ static void set_queue_congested(request_queue_t *q, int rw)
 
 /**
  * blk_get_backing_dev_info - get the address of a queue's backing_dev_info
- * @dev:       device
+ * @bdev:      device
  *
  * Locates the passed device's request queue and returns the address of its
  * backing_dev_info
@@ -414,8 +414,8 @@ void blk_queue_segment_boundary(request_queue_t *q, unsigned long mask)
 
 /**
  * blk_queue_dma_alignment - set dma length and memory alignment
- * @q:  the request queue for the device
- * @dma_mask:  alignment mask
+ * @q:     the request queue for the device
+ * @mask:  alignment mask
  *
  * description:
  *    set required memory and length aligment for direct dma transactions.
@@ -1152,7 +1152,7 @@ void blk_stop_queue(request_queue_t *q)
 
 /**
  * blk_run_queue - run a single device queue
- * @q  The queue to run
+ * @q: The queue to run
  */
 void blk_run_queue(struct request_queue *q)
 {

diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c
index 3227f4dfdede03997fbbfa7d3be511441a1201e2..0ed0c02fc5ab7ce0b7b889599d333b3d5efa98e6 100644 (file)
--- a/drivers/pci/pci.c
+++ b/drivers/pci/pci.c
@@ -126,11 +126,13 @@ pci_find_capability(struct pci_dev *dev, int cap)
 
 /**
  * pci_bus_find_capability - query for devices' capabilities 
- * @dev: PCI device to query
- * @cap: capability code
+ * @bus:   the PCI bus to query
+ * @devfn: PCI device to query
+ * @cap:   capability code
  *
  * Like pci_find_capability() but works for pci devices that do not have a
  * pci_dev structure set up yet. 
+ *
  * Returns the address of the requested capability structure within the
  * device's PCI configuration space or 0 in case the device does not
  * support it.

diff --git a/drivers/serial/8250.c b/drivers/serial/8250.c
index 7d0479c472ca466e9ff0a783687ceaa10a5a21c1..2a4d196155298c389be338f708a38a06ed927757 100644 (file)
--- a/drivers/serial/8250.c
+++ b/drivers/serial/8250.c
@@ -2111,7 +2111,8 @@ void serial8250_get_irq_map(unsigned int *map)
 
 /**
  *     serial8250_suspend_port - suspend one serial port
- *     @line: serial line number
+ *     @line:  serial line number
+ *      @level: the level of port suspension, as per uart_suspend_port
  *
  *     Suspend one serial port.
  */
@@ -2122,7 +2123,8 @@ void serial8250_suspend_port(int line)
 
 /**
  *     serial8250_resume_port - resume one serial port
- *     @line: serial line number
+ *     @line:  serial line number
+ *      @level: the level of port resumption, as per uart_resume_port
  *
  *     Resume one serial port.
  */

diff --git a/drivers/serial/serial_core.c b/drivers/serial/serial_core.c
index 064b9631201fb8da5ac8e29f6e212834af811721..6cf18b46136fa35be4c2638418080b82d29cafe1 100644 (file)
--- a/drivers/serial/serial_core.c
+++ b/drivers/serial/serial_core.c
@@ -263,9 +263,9 @@ static void uart_shutdown(struct uart_state *state)
 
 /**
  *     uart_update_timeout - update per-port FIFO timeout.
- *     @port: uart_port structure describing the port.
+ *     @port:  uart_port structure describing the port
  *     @cflag: termios cflag value
- *     @quot: uart clock divisor quotient
+ *     @baud:  speed of the port
  *
  *     Set the port FIFO timeout value.  The @cflag value should
  *     reflect the actual hardware settings.

diff --git a/fs/devfs/base.c b/fs/devfs/base.c
index 73894d9af19c1c30f18c1ff383d846c814fe5c8d..1d8b7410e175da1feeace6bb8bcaeac9e0103bcd 100644 (file)
--- a/fs/devfs/base.c
+++ b/fs/devfs/base.c
@@ -973,8 +973,9 @@ static struct devfs_entry *_devfs_search_dir (struct devfs_entry *dir,
 
 /**
  *     _devfs_alloc_entry - Allocate a devfs entry.
- *     @name:  The name of the entry.
- *     @namelen:  The number of characters in @name.
+ *     @name:     the name of the entry
+ *     @namelen:  the number of characters in @name
+ *      @mode:     the mode for the entry
  *
  *  Allocate a devfs entry and returns a pointer to the entry on success, else
  *   %NULL.

diff --git a/fs/inode.c b/fs/inode.c
index 71c2c4d37697a9e01dadca219e74b1482b06b472..76d7881f2b606fbbb7a3bc687a1809a893b75395 100644 (file)
--- a/fs/inode.c
+++ b/fs/inode.c
@@ -255,6 +255,9 @@ void clear_inode(struct inode *inode)
 EXPORT_SYMBOL(clear_inode);
 
 /*
+ * dispose_list - dispose of the contents of a local list
+ * @head: the head of the list to free
+ *
  * Dispose-list gets a local list with local inodes in it, so it doesn't
  * need to worry about list corruption and SMP locks.
  */
@@ -739,11 +742,11 @@ EXPORT_SYMBOL(igrab);
 /**
  * ifind - internal function, you want ilookup5() or iget5().
  * @sb:                super block of file system to search
- * @hashval:   hash value (usually inode number) to search for
+ * @head:       the head of the list to search
  * @test:      callback used for comparisons between inodes
  * @data:      opaque data pointer to pass to @test
  *
- * ifind() searches for the inode specified by @hashval and @data in the inode
+ * ifind() searches for the inode specified by @data in the inode
  * cache. This is a generalized version of ifind_fast() for file systems where
  * the inode number is not sufficient for unique identification of an inode.
  *
@@ -775,6 +778,7 @@ static inline struct inode *ifind(struct super_block *sb,
 /**
  * ifind_fast - internal function, you want ilookup() or iget().
  * @sb:                super block of file system to search
+ * @head:       head of the list to search
  * @ino:       inode number to search for
  *
  * ifind_fast() searches for the inode @ino in the inode cache. This is for

diff --git a/fs/locks.c b/fs/locks.c
index d7a2688c8e5c61472e2a6c7b4f604755f40c822e..9fc4b5cd5c647764dcbb1f7fe6440c95450833f1 100644 (file)
--- a/fs/locks.c
+++ b/fs/locks.c
@@ -928,10 +928,10 @@ int locks_mandatory_locked(struct inode *inode)
  * locks_mandatory_area - Check for a conflicting lock
  * @read_write: %FLOCK_VERIFY_WRITE for exclusive access, %FLOCK_VERIFY_READ
  *             for shared
- * @inode: the file to check
- * @file: how the file was opened (if it was)
- * @offset: start of area to check
- * @count: length of area to check
+ * @inode:      the file to check
+ * @filp:       how the file was opened (if it was)
+ * @offset:     start of area to check
+ * @count:      length of area to check
  *
  * Searches the inode's list of locks to find any POSIX locks which conflict.
  * This function is called from locks_verify_area() and
@@ -1119,6 +1119,7 @@ out:
 /**
  *     lease_get_mtime
  *     @inode: the inode
+ *      @time:  pointer to a timespec which will contain the last modified time
  *
  * This is to force NFS clients to flush their caches for files with
  * exclusive leases.  The justification is that if someone has an
@@ -1726,6 +1727,7 @@ posix_block_lock(struct file_lock *blocker, struct file_lock *waiter)
 
 /**
  *     posix_unblock_lock - stop waiting for a file lock
+ *      @filp:   how the file was opened
  *     @waiter: the lock which was waiting
  *
  *     lockd needs to block waiting for locks.

diff --git a/fs/super.c b/fs/super.c
index 67a0175290567c7442b4bb2964557ea6fea7cc40..2117f5c124235b03de95f7bd9543926f7c91e63b 100644 (file)
--- a/fs/super.c
+++ b/fs/super.c
@@ -138,8 +138,8 @@ void deactivate_super(struct super_block *s)
 EXPORT_SYMBOL(deactivate_super);
 
 /**
- *     grab_super      - acquire an active reference
- *     @s      - reference we are trying to make active
+ *     grab_super - acquire an active reference
+ *     @s: reference we are trying to make active
  *
  *     Tries to acquire an active reference.  grab_super() is used when we
  *     had just found a superblock in super_blocks or fs_type->fs_supers
@@ -368,8 +368,8 @@ restart:
 }
 
 /**
- *     get_super       -       get the superblock of a device
- *     @dev: device to get the superblock for
+ *     get_super - get the superblock of a device
+ *     @bdev: device to get the superblock for
  *     
  *     Scans the superblock list and finds the superblock of the file system
  *     mounted on the device given. %NULL is returned if no match is found.
@@ -461,10 +461,11 @@ static void mark_files_ro(struct super_block *sb)
 }
 
 /**
- *     do_remount_sb   -       asks filesystem to change mount options.
+ *     do_remount_sb - asks filesystem to change mount options.
  *     @sb:    superblock in question
  *     @flags: numeric part of options
  *     @data:  the rest of options
+ *      @force: whether or not to force the change
  *
  *     Alters the mount options of a mounted file system.
  */

diff --git a/include/linux/list.h b/include/linux/list.h
index 9e218f0e471c0ea612a1286c5afae207460786ac..5fdf945bbf9382f810ccdc472f9b4a32e11f18f9 100644 (file)
--- a/include/linux/list.h
+++ b/include/linux/list.h
@@ -449,7 +449,7 @@ static __inline__ void hlist_del(struct hlist_node *n)
 
 /**
  * hlist_del_rcu - deletes entry from hash list without re-initialization
- * @entry: the element to delete from the hash list.
+ * @n: the element to delete from the hash list.
  *
  * Note: list_unhashed() on entry does not return true after this, 
  * the entry is in an undefined state. It is useful for RCU based

diff --git a/include/linux/skbuff.h b/include/linux/skbuff.h
index 81b3289dbe68d39ef40bb2cfbacc897d60a91711..2aeb35d62c2d2e4865db3ff272258e0cd23271fe 100644 (file)
--- a/include/linux/skbuff.h
+++ b/include/linux/skbuff.h
@@ -152,6 +152,7 @@ struct skb_shared_info {
  *     @sk: Socket we are owned by
  *     @stamp: Time we arrived
  *     @dev: Device we arrived on/are leaving by
+ *      @real_dev: The real device we are using
  *     @h: Transport layer header
  *     @nh: Network layer header
  *     @mac: Link layer header
@@ -179,6 +180,7 @@ struct skb_shared_info {
  *     @nfct: Associated connection, if any
  *     @nf_debug: Netfilter debugging
  *     @nf_bridge: Saved data about a bridged frame - see br_netfilter.c
+ *      @private: Data which is private to the HIPPI implementation
  *     @tc_index: Traffic control index
  */
 

diff --git a/kernel/kmod.c b/kernel/kmod.c
index 98d8096890926bae6fbc3b7c7d0c6124fd3c9004..f5d658f704d93e5a0570a07434653671203da8d9 100644 (file)
--- a/kernel/kmod.c
+++ b/kernel/kmod.c
@@ -47,7 +47,8 @@ char modprobe_path[256] = "/sbin/modprobe";
 
 /**
  * request_module - try to load a kernel module
- * @module_name: Name of module
+ * @fmt:     printf style format string for the name of the module
+ * @varargs: arguements as specified in the format string
  *
  * Load a module using the user mode module loader. The function returns
  * zero on success or a negative errno code on failure. Note that a

diff --git a/mm/slab.c b/mm/slab.c
index 76c95b542be650ae4c4a4c701305f0a1e4b3b3e1..3b216e910d5ec99520eff968cb397e35f5f53606 100644 (file)
--- a/mm/slab.c
+++ b/mm/slab.c
@@ -2675,8 +2675,8 @@ struct seq_operations slabinfo_op = {
  * slabinfo_write - Tuning for the slab allocator
  * @file: unused
  * @buffer: user buffer
- * @count: data len
- * @data: unused
+ * @count: data length
+ * @ppos: unused
  */
 ssize_t slabinfo_write(struct file *file, const char __user *buffer,
                                size_t count, loff_t *ppos)

diff --git a/net/core/dev.c b/net/core/dev.c
index 49c662e1d31d52b3f444ff2bc3c8c0f9598dec39..b601f110b1b9ef0de6ad22d87c1ce982ea396b18 100644 (file)
--- a/net/core/dev.c
+++ b/net/core/dev.c
@@ -915,6 +915,8 @@ int unregister_netdevice_notifier(struct notifier_block *nb)
 
 /**
  *     call_netdevice_notifiers - call all network notifier blocks
+ *      @val: value passed unmodified to notifier function
+ *      @v:   pointer passed unmodified to notifier function
  *
  *     Call all network notifier blocks.  Parameters and return value
  *     are as for notifier_call_chain().

diff --git a/sound/oss/via82cxxx_audio.c b/sound/oss/via82cxxx_audio.c
index 1836e6934af2ebcdd888ad6dd1cd7cfb85bc2829..360306ecae435faf7b485ccb8d7c0fca54fb90c5 100644 (file)
--- a/sound/oss/via82cxxx_audio.c
+++ b/sound/oss/via82cxxx_audio.c
@@ -1844,6 +1844,7 @@ static void via_ac97_cleanup (struct via_info *card)
 
 /**
  *     via_intr_channel - handle an interrupt for a single channel
+ *      @card: unused
  *     @chan: handle interrupt for this channel
  *
  *     This is the "meat" of the interrupt handler,