Here's a short patch to make some of the inline documentation consistent
with the rest of it.
That means putting '%' in front of constants, '()' after function names,
'&' in front of struct names (hey, I didn't choose it..), and so on.
Does anyone have any complaints about it before I send it to Linus?
Tim.
*/
diff -durN linux-2.3.99-pre4-4/arch/i386/kernel/irq.c linux/arch/i386/kernel/irq.c
--- linux-2.3.99-pre4-4/arch/i386/kernel/irq.c Wed Apr 5 16:45:32 2000
+++ linux/arch/i386/kernel/irq.c Wed Apr 5 21:43:36 2000
@@ -462,8 +462,8 @@
* @irq: Interrupt to disable
*
* Disable the selected interrupt line. Disables of an interrupt
- * stack. Unlike disable_irq, this function does not ensure existing
- * instances of the irq handler have completed before returning.
+ * stack. Unlike disable_irq(), this function does not ensure existing
+ * instances of the IRQ handler have completed before returning.
*
* This function may be called from IRQ context.
*/
diff -durN linux-2.3.99-pre4-4/arch/i386/kernel/mca.c linux/arch/i386/kernel/mca.c
--- linux-2.3.99-pre4-4/arch/i386/kernel/mca.c Fri Mar 17 18:35:02 2000
+++ linux/arch/i386/kernel/mca.c Wed Apr 5 21:47:08 2000
@@ -366,12 +366,12 @@
/**
* mca_find_adapter - scan for adapters
* @id: MCA identification to search for
- * @start: Starting slot
+ * @start: starting slot
*
* Search the MCA configuration for adapters matching the 16bit
* ID given. The first time it should be called with start as zero
* and then further calls made passing the return value of the
- * previous call until MCA_NOTFOUND is returned.
+ * previous call until %MCA_NOTFOUND is returned.
*
* Disabled adapters are not reported.
*/
@@ -411,12 +411,12 @@
/**
* mca_find_unused_adapter - scan for unused adapters
* @id: MCA identification to search for
- * @start: Starting slot
+ * @start: starting slot
*
* Search the MCA configuration for adapters matching the 16bit
* ID given. The first time it should be called with start as zero
* and then further calls made passing the return value of the
- * previous call until MCA_NOTFOUND is returned.
+ * previous call until %MCA_NOTFOUND is returned.
*
* Adapters that have been claimed by drivers and those that
* are disabled are not reported. This function thus allows a driver
@@ -647,10 +647,10 @@
* function is called with the buffer, slot, and device pointer (or
* some equally informative context information, or nothing, if you
* prefer), and is expected to put useful information into the
- * buffer. The adapter name, id, and POS registers get printed
+ * buffer. The adapter name, ID, and POS registers get printed
* before this is called though, so don't do it again.
*
- * This should be called with a NULL procfn when a module
+ * This should be called with a %NULL @procfn when a module
* unregisters, thus preventing kernel crashes and other such
* nastiness.
*/
diff -durN linux-2.3.99-pre4-4/arch/i386/kernel/mtrr.c linux/arch/i386/kernel/mtrr.c
--- linux-2.3.99-pre4-4/arch/i386/kernel/mtrr.c Wed Apr 5 16:45:32 2000
+++ linux/arch/i386/kernel/mtrr.c Wed Apr 5 21:45:27 2000
@@ -1110,7 +1110,7 @@
*
* Memory type region registers control the caching on newer Intel and
* non Intel processors. This function allows drivers to request an
- * MTRR is added. The details and hardware specifics of each processors
+ * MTRR is added. The details and hardware specifics of each processor's
* implementation are hidden from the caller, but nevertheless the
* caller should expect to need to provide a power of two size on an
* equivalent power of two boundary.
@@ -1125,13 +1125,13 @@
*
* The available types are
*
- * MTRR_TYPE_UNCACHEABLE - No caching
+ * %MTRR_TYPE_UNCACHEABLE - No caching
*
- * MTRR_TYPE_WRITEBACK - Write data back in bursts whenever
+ * %MTRR_TYPE_WRITEBACK - Write data back in bursts whenever
*
- * MTRR_TYPE_WRCOMB - Write data back soon but allow bursts
+ * %MTRR_TYPE_WRCOMB - Write data back soon but allow bursts
*
- * MTRR_TYPE_WRTHROUGH - Cache reads but not writes
+ * %MTRR_TYPE_WRTHROUGH - Cache reads but not writes
*
* BUGS: Needs a quiet flag for the cases where drivers do not mind
* failures and do not wish system log messages to be sent.
diff -durN linux-2.3.99-pre4-4/drivers/char/misc.c linux/drivers/char/misc.c
--- linux-2.3.99-pre4-4/drivers/char/misc.c Fri Mar 24 08:23:16 2000
+++ linux/drivers/char/misc.c Wed Apr 5 21:51:20 2000
@@ -138,12 +138,12 @@
* @misc: device structure
*
* Register a miscellaneous device with the kernel. If the minor
- * number is set to MISC_DYNAMIC_MINOR a minor number is assigned
+ * number is set to %MISC_DYNAMIC_MINOR a minor number is assigned
* and placed in the minor field of the structure. For other cases
* the minor number requested is used.
*
* The structure passed is linked into the kernel and may not be
- * destroyed until it has been unregistered
+ * destroyed until it has been unregistered.
*
* A zero is returned on success and a negative errno code for
* failure.
@@ -195,7 +195,7 @@
* @misc: device to unregister
*
* Unregister a miscellaneous device that was previously
- * successfully registered with misc_register. Success
+ * successfully registered with misc_register()F. Success
* is indicated by a zero return, a negative errno code
* indicates an error.
*/
diff -durN linux-2.3.99-pre4-4/drivers/char/serial.c linux/drivers/char/serial.c
--- linux-2.3.99-pre4-4/drivers/char/serial.c Wed Apr 5 16:45:34 2000
+++ linux/drivers/char/serial.c Wed Apr 5 21:56:18 2000
@@ -4683,7 +4683,7 @@
*
* The port specified is deconfigured and its resources are freed. Any
* user of the port is disconnected as if carrier was dropped. Line is
- * the port number returned by register_serial.
+ * the port number returned by register_serial().
*/
void unregister_serial(int line)
diff -durN linux-2.3.99-pre4-4/drivers/char/videodev.c linux/drivers/char/videodev.c
--- linux-2.3.99-pre4-4/drivers/char/videodev.c Wed Apr 5 16:45:34 2000
+++ linux/drivers/char/videodev.c Wed Apr 5 21:53:30 2000
@@ -221,26 +221,26 @@
/**
* video_register_device - register video4linux devices
- * @vfd: Video device structure we want to register
+ * @vfd: video device structure we want to register
* @type: type of device to register
* FIXME: needs a semaphore on 2.3.x
*
* The registration code assigns minor numbers based on the type
* requested. -ENFILE is returned in all the device slots for this
* catetory are full. If not then the minor field is set and the
- * driver initialize function is called (if non NULL).
+ * driver initialize function is called (if non %NULL).
*
* Zero is returned on success.
*
* Valid types are
*
- * VFL_TYPE_GRABBER - A frame grabber
+ * %VFL_TYPE_GRABBER - A frame grabber
*
- * VFL_TYPE_VTX - A teletext device
+ * %VFL_TYPE_VTX - A teletext device
*
- * VFL_TYPE_VBI - Vertical blank data (undecoded)
+ * %VFL_TYPE_VBI - Vertical blank data (undecoded)
*
- * VFL_TYPE_RADIO - A radio card
+ * %VFL_TYPE_RADIO - A radio card
*/
int video_register_device(struct video_device *vfd, int type)
diff -durN linux-2.3.99-pre4-4/drivers/net/8390.c linux/drivers/net/8390.c
--- linux-2.3.99-pre4-4/drivers/net/8390.c Wed Apr 5 16:45:34 2000
+++ linux/drivers/net/8390.c Wed Apr 5 21:40:34 2000
@@ -181,7 +181,7 @@
* ei_close - shut down network device
* @dev: network device to close
*
- * Opposite of ei_open. Only used when "ifconfig <devname> down" is done.
+ * Opposite of ei_open(). Only used when "ifconfig <devname> down" is done.
*/
int ei_close(struct net_device *dev)
{
@@ -416,7 +416,7 @@
* the 8390 via the card specific functions and fire them at the networking
* stack. We also handle transmit completions and wake the transmit path if
* neccessary. We also update the counters and do other housekeeping as
- * needed
+ * needed.
*/
void ei_interrupt(int irq, void *dev_id, struct pt_regs * regs)
@@ -530,7 +530,7 @@
* is a much better solution as it avoids kernel based Tx timeouts, and
* an unnecessary card reset.
*
- * Called with lock held
+ * Called with lock held.
*/
static void ei_tx_err(struct net_device *dev)
@@ -573,7 +573,7 @@
* @dev: network device for which tx intr is handled
*
* We have finished a transmit: check for errors and then trigger the next
- * packet to be sent. Called with lock held
+ * packet to be sent. Called with lock held.
*/
static void ei_tx_intr(struct net_device *dev)
@@ -665,7 +665,7 @@
* @dev: network device with which receive will be run
*
* We have a good packet(s), get it/them out of the buffers.
- * Called with lock held
+ * Called with lock held.
*/
static void ei_receive(struct net_device *dev)
@@ -801,7 +801,7 @@
* This includes causing "the NIC to defer indefinitely when it is stopped
* on a busy network." Ugh.
* Called with lock held. Don't call this with the interrupts off or your
- * computer will hate you - it takes 10mS or so.
+ * computer will hate you - it takes 10ms or so.
*/
static void ei_rx_overrun(struct net_device *dev)
diff -durN linux-2.3.99-pre4-4/drivers/net/wan/syncppp.c linux/drivers/net/wan/syncppp.c
--- linux-2.3.99-pre4-4/drivers/net/wan/syncppp.c Fri Mar 17 18:35:06 2000
+++ linux/drivers/net/wan/syncppp.c Wed Apr 5 21:42:52 2000
@@ -193,7 +193,7 @@
*
* This can be called directly by cards that do not have
* timing constraints but is normally called from the network layer
- * after interrupt servicing to process frames queued via netif_rx.
+ * after interrupt servicing to process frames queued via netif_rx().
*
* We process the options in the card. If the frame is destined for
* the protocol stacks then it requeues the frame for the upper level
diff -durN linux-2.3.99-pre4-4/drivers/net/wan/z85230.c linux/drivers/net/wan/z85230.c
--- linux-2.3.99-pre4-4/drivers/net/wan/z85230.c Wed Apr 5 16:45:34 2000
+++ linux/drivers/net/wan/z85230.c Wed Apr 5 21:57:33 2000
@@ -1313,12 +1313,12 @@
/**
* z8530_channel_load - Load channel data
* @c: Z8530 channel to configure
- * @rtable: Table of register, value pairs
+ * @rtable: table of register, value pairs
* FIXME: ioctl to allow user uploaded tables
*
* Load a Z8530 channel up from the system data. We use +16 to
- * indicate the 'prime' registers. The value 255 terminates the
- * table
+ * indicate the "prime" registers. The value 255 terminates the
+ * table.
*/
int z8530_channel_load(struct z8530_channel *c, u8 *rtable)
diff -durN linux-2.3.99-pre4-4/drivers/sound/sound_core.c linux/drivers/sound/sound_core.c
--- linux-2.3.99-pre4-4/drivers/sound/sound_core.c Wed Apr 5 16:45:35 2000
+++ linux/drivers/sound/sound_core.c Wed Apr 5 21:55:38 2000
@@ -370,10 +370,11 @@
/**
* unregister_sound_special - unregister a special sound device
- * @unit: Unit number to allocate
+ * @unit: unit number to allocate
*
- * Release a sound device that was allocated with register_sound_special.
- * The unit passed is the return value from the register function.
+ * Release a sound device that was allocated with
+ * register_sound_special(). The unit passed is the return value from
+ * the register function.
*/
@@ -386,9 +387,9 @@
/**
* unregister_sound_mixer - unregister a mixer
- * @unit: Unit number to allocate
+ * @unit: unit number to allocate
*
- * Release a sound device that was allocated with register_sound_mixer.
+ * Release a sound device that was allocated with register_sound_mixer().
* The unit passed is the return value from the register function.
*/
@@ -401,9 +402,9 @@
/**
* unregister_sound_midi - unregister a midi device
- * @unit: Unit number to allocate
+ * @unit: unit number to allocate
*
- * Release a sound device that was allocated with register_sound_midi.
+ * Release a sound device that was allocated with register_sound_midi().
* The unit passed is the return value from the register function.
*/
@@ -416,9 +417,9 @@
/**
* unregister_sound_dsp - unregister a DSP device
- * @unit: Unit number to allocate
+ * @unit: unit number to allocate
*
- * Release a sound device that was allocated with register_sound_dsp.
+ * Release a sound device that was allocated with register_sound_dsp().
* The unit passed is the return value from the register function.
*
* Both of the allocated units are released together automatically.
@@ -434,9 +435,9 @@
/**
* unregister_sound_synth - unregister a synth device
- * @unit: Unit number to allocate
+ * @unit: unit number to allocate
*
- * Release a sound device that was allocated with register_sound_synth.
+ * Release a sound device that was allocated with register_sound_synth().
* The unit passed is the return value from the register function.
*/
diff -durN linux-2.3.99-pre4-4/fs/bad_inode.c linux/fs/bad_inode.c
--- linux-2.3.99-pre4-4/fs/bad_inode.c Wed Apr 5 16:45:36 2000
+++ linux/fs/bad_inode.c Wed Apr 5 21:17:43 2000
@@ -78,8 +78,8 @@
* @inode: Inode to mark bad
*
* When an inode cannot be read due to a media or remote network
- * failure this function makes the inode 'bad' and causes I/O operations
- * on it to fail from this point on
+ * failure this function makes the inode "bad" and causes I/O operations
+ * on it to fail from this point on.
*/
void make_bad_inode(struct inode * inode)
@@ -100,7 +100,7 @@
* is_bad_inode - is an inode errored
* @inode: inode to test
*
- * Returns true if the inode in question has been marked as bad
+ * Returns true if the inode in question has been marked as bad.
*/
int is_bad_inode(struct inode * inode)
diff -durN linux-2.3.99-pre4-4/fs/dcache.c linux/fs/dcache.c
--- linux-2.3.99-pre4-4/fs/dcache.c Wed Apr 5 16:45:36 2000
+++ linux/fs/dcache.c Wed Apr 5 21:13:28 2000
@@ -83,7 +83,7 @@
}
/*
- * dput
+ * This is dput
*
* This is complicated by the fact that we do not want to put
* dentries that are no longer on any hash chain on the unused
@@ -534,7 +534,7 @@
* @parent: parent of entry to allocate
* @name: qstr of the name
*
- * Allocates a dentry. It returns NULL if there is insufficient memory
+ * Allocates a dentry. It returns %NULL if there is insufficient memory
* available. On a success the dentry is returned. The name passed in is
* copied and the copy passed in may be reused after this call.
*/
@@ -590,7 +590,7 @@
/**
* d_instantiate - fill in inode information for a dentry
* @entry: dentry to complete
- * @inode: inode to attacheto this dentry
+ * @inode: inode to attach to this dentry
*
* Fill in inode information in the entry.
*
@@ -599,7 +599,7 @@
*
* NOTE! This assumes that the inode count has been incremented
* (or otherwise set) by the caller to indicate that it is now
- * in use by the dcache..
+ * in use by the dcache.
*/
void d_instantiate(struct dentry *entry, struct inode * inode)
@@ -613,9 +613,9 @@
* d_alloc_root - allocate root dentry
* @root_inode: inode to allocate the root for
*
- * Allocate a root ('/') dentry for the inode given. The inode is
- * instantiated and returned. NULL is returned if there is insufficient
- * memory or the inode passed is NULL.
+ * Allocate a root ("/") dentry for the inode given. The inode is
+ * instantiated and returned. %NULL is returned if there is insufficient
+ * memory or the inode passed is %NULL.
*/
struct dentry * d_alloc_root(struct inode * root_inode)
@@ -648,7 +648,7 @@
* Searches the children of the parent dentry for the name in question. If
* the dentry is found its reference count is incremented and the dentry
* is returned. The caller must use d_put to free the entry when it has
- * finished using it. NULL is returned on failure.
+ * finished using it. %NULL is returned on failure.
*/
struct dentry * d_lookup(struct dentry * parent, struct qstr * name)
@@ -780,7 +780,7 @@
* d_rehash - add an entry back to the hash
* @entry: dentry to add to the hash
*
- * Adds a dentry to the hash according to its name
+ * Adds a dentry to the hash according to its name.
*/
void d_rehash(struct dentry * entry)
@@ -881,11 +881,11 @@
* @buffer: buffer to return value in
* @buflen: buffer length
*
- * Convert a dentry into an ascii path name. If the entry has been deleted
- * the string ' (deleted)' is appended. Note that this is ambiguous. Returns
+ * Convert a dentry into an ASCII path name. If the entry has been deleted
+ * the string " (deleted)" is appended. Note that this is ambiguous. Returns
* the buffer.
*
- * "buflen" should be PAGE_SIZE or more.
+ * "buflen" should be %PAGE_SIZE or more.
*/
char * __d_path(struct dentry *dentry, struct vfsmount *vfsmnt,
struct dentry *root, struct vfsmount *rootmnt,
diff -durN linux-2.3.99-pre4-4/fs/inode.c linux/fs/inode.c
--- linux-2.3.99-pre4-4/fs/inode.c Wed Apr 5 16:45:37 2000
+++ linux/fs/inode.c Wed Apr 5 21:16:38 2000
@@ -116,7 +116,7 @@
* __mark_inode_dirty - internal function
* @inode: inode to mark
*
- * Mark an inode as dirty. Callers should use mark_inode_dirty
+ * Mark an inode as dirty. Callers should use mark_inode_dirty.
*/
void __mark_inode_dirty(struct inode *inode)
@@ -530,7 +530,7 @@
* no pre-existing information.
*
* On a successful return the inode pointer is returned. On a failure
- * a NULL pointer is returned. The returned inode is not on any superblock
+ * a %NULL pointer is returned. The returned inode is not on any superblock
* lists.
*/
@@ -707,7 +707,7 @@
* @inode: unhashed inode
*
* Add an inode to the inode hash for this superblock. If the inode
- * has no superblock it is added to a seperate anonymous chain
+ * has no superblock it is added to a separate anonymous chain.
*/
void insert_inode_hash(struct inode *inode)
@@ -724,7 +724,7 @@
* remove_inode_hash - remove an inode from the hash
* @inode: inode to unhash
*
- * Remove an inode from the superblock or anonymous hash
+ * Remove an inode from the superblock or anonymous hash.
*/
void remove_inode_hash(struct inode *inode)
@@ -829,9 +829,9 @@
*
* Returns the block number on the device holding the inode that
* is the disk block number for the block of the file requested.
- * That is asked for block 4 of inode 1 the function will return the
+ * That is, asked for block 4 of inode 1 the function will return the
* disk block relative to the disk start that holds that block of the
- * file
+ * file.
*/
int bmap(struct inode * inode, int block)
@@ -869,9 +869,9 @@
* update_atime - update the access time
* @inode: inode accessed
*
- * Update the accessed time on an inode and mark it for writeback.
+ * Update the accessed time on an inode and mark it for writeback.
* This function automatically handles read only file systems and media,
- * as well as the noatime flag and inode specific noatime markers
+ * as well as the "noatime" flag and inode specific "noatime" markers.
*/
void update_atime (struct inode *inode)
diff -durN linux-2.3.99-pre4-4/fs/super.c linux/fs/super.c
--- linux-2.3.99-pre4-4/fs/super.c Wed Apr 5 16:45:39 2000
+++ linux/fs/super.c Wed Apr 5 21:20:24 2000
@@ -96,10 +96,10 @@
* @fs: the file system structure
*
* Adds the file system passed to the list of file systems the kernel
- * is aware of for by mount and other syscalls. Returns 0 on success,
+ * is aware of for mount and other syscalls. Returns 0 on success,
* or a negative errno code on an error.
*
- * The file_system_type that is passed is linked into the kernel
+ * The &struct file_system_type that is passed is linked into the kernel
* structures and must not be freed until the file system has been
* unregistered.
*/
@@ -131,8 +131,8 @@
* with the kernel. An error is returned if the file system is not found.
* Zero is returned on a success.
*
- * Once this function has returned the file_system_type structure may be
- * freed or reused.
+ * Once this function has returned the &struct file_system_type structure
+ * may be freed or reused.
*/
int unregister_filesystem(struct file_system_type * fs)
@@ -456,7 +456,7 @@
* @sb: superblock to wait on
*
* Waits for a superblock to become unlocked and then returns. It does
- * not take the lock. This is an internal function. See wait_on_super.
+ * not take the lock. This is an internal function. See wait_on_super().
*/
void __wait_on_super(struct super_block * sb)
@@ -505,10 +505,10 @@
/**
* get_super - get the superblock of a device
- * @dev: device to get the super block for
+ * @dev: 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.
+ * mounted on the device given. %NULL is returned if no match is found.
*/
struct super_block * get_super(kdev_t dev)
@@ -558,10 +558,10 @@
/**
* get_empty_super - find empty superblocks
*
- * Find a super_block with no device assigned. A free superblock is
+ * Find a superblock with no device assigned. A free superblock is
* found and returned. If neccessary new superblocks are allocated.
- * NULL is returned if there are insufficient resources to complete
- * the request
+ * %NULL is returned if there are insufficient resources to complete
+ * the request.
*/
struct super_block *get_empty_super(void)
diff -durN linux-2.3.99-pre4-4/include/asm-i386/mca_dma.h linux/include/asm-i386/mca_dma.h
--- linux-2.3.99-pre4-4/include/asm-i386/mca_dma.h Fri Mar 17 18:35:25 2000
+++ linux/include/asm-i386/mca_dma.h Wed Apr 5 21:48:28 2000
@@ -178,18 +178,18 @@
/**
* mca_set_dma_mode - set the DMA mode
* @dmanr: DMA channel
- * @mode: The mode to set
+ * @mode: mode to set
*
* The DMA controller supports several modes. The mode values you can
- * set are
+ * set are :
*
- * MCA_DMA_MODE_READ when reading from the DMA device.
+ * %MCA_DMA_MODE_READ when reading from the DMA device.
*
- * MCA_DMA_MODE_WRITE to writing to the DMA device.
+ * %MCA_DMA_MODE_WRITE to writing to the DMA device.
*
- * MCA_DMA_MODE_IO to do DMA to or from an I/O port.
+ * %MCA_DMA_MODE_IO to do DMA to or from an I/O port.
*
- * MCA_DMA_MODE_16 to do 16bit transfers.
+ * %MCA_DMA_MODE_16 to do 16bit transfers.
*
*/
diff -durN linux-2.3.99-pre4-4/include/linux/dcache.h linux/include/linux/dcache.h
--- linux-2.3.99-pre4-4/include/linux/dcache.h Wed Apr 5 16:45:41 2000
+++ linux/include/linux/dcache.h Wed Apr 5 21:14:18 2000
@@ -177,8 +177,8 @@
* @entry: dentry to add
* @inode: The inode to attach to this dentry
*
- * This adds the entry to the hash queues and initializes "d_inode".
- * The entry was actually filled in earlier during "d_alloc()"
+ * This adds the entry to the hash queues and initializes @inode.
+ * The entry was actually filled in earlier during d_alloc().
*/
static __inline__ void d_add(struct dentry * entry, struct inode * inode)
@@ -207,9 +207,9 @@
/**
* dget - get a reference to a dentry
- * @dentry: dentry to get a reference too
+ * @dentry: dentry to get a reference to
*
- * Given a dentry or NULL pointer increment the reference count
+ * Given a dentry or %NULL pointer increment the reference count
* if appropriate and return the dentry. A dentry will not be
* destroyed when it has references.
*/
@@ -225,7 +225,7 @@
* d_unhashed - is dentry hashed
* @dentry: entry to check
*
- * Returns true if the dentry passed is not currently hashed
+ * Returns true if the dentry passed is not currently hashed.
*/
static __inline__ int d_unhashed(struct dentry *dentry)
diff -durN linux-2.3.99-pre4-4/include/linux/skbuff.h linux/include/linux/skbuff.h
--- linux-2.3.99-pre4-4/include/linux/skbuff.h Wed Apr 5 16:45:54 2000
+++ linux/include/linux/skbuff.h Wed Apr 5 21:27:54 2000
@@ -211,7 +211,7 @@
* skb_queue_empty - check if a queue is empty
* @list: queue head
*
- * Returns true if the queue is empty, false otherwise
+ * Returns true if the queue is empty, false otherwise.
*/
extern __inline__ int skb_queue_empty(struct sk_buff_head *list)
@@ -240,7 +240,7 @@
/**
* kfree_skb - free an sk_buff
- * @skb: The buffer to free
+ * @skb: buffer to free
*
* Drop a reference to the buffer and free it if the usage count has
* hit zero.
@@ -261,9 +261,9 @@
/**
* skb_cloned - is the buffer a clone
- * @skb: Buffer to check
+ * @skb: buffer to check
*
- * Returns true if the buffer was generated with skb_clone and is
+ * Returns true if the buffer was generated with skb_clone() and is
* one of multiple shared copies of the buffer. Cloned buffers are
* shared data so must not be written to under normal circumstances.
*/
@@ -328,9 +328,9 @@
* copy of the data, drops a reference count on the old copy and returns
* the new copy with the reference count at 1. If the buffer is not a clone
* the original buffer is returned. When called with a spinlock held or
- * from interrupt state pri must be GFP_ATOMIC
+ * from interrupt state @pri must be %GFP_ATOMIC
*
- * NULL is returned on a memory allocation failure.
+ * %NULL is returned on a memory allocation failure.
*/
extern __inline__ struct sk_buff *skb_unshare(struct sk_buff *skb, int pri)
@@ -347,12 +347,12 @@
* skb_peek
* @list_: list to peek at
*
- * Peek an sk_buff. Unlike most other operations you _MUST_
+ * Peek an &sk_buff. Unlike most other operations you _MUST_
* be careful with this one. A peek leaves the buffer on the
* list and someone else may run off with it. You must hold
* the appropriate locks or have a private queue to do this.
*
- * Returns NULL for an empty list or a pointer to the head element.
+ * Returns %NULL for an empty list or a pointer to the head element.
* The reference count is not incremented and the reference is therefore
* volatile. Use with caution.
*/
@@ -369,12 +369,12 @@
* skb_peek_tail
* @list_: list to peek at
*
- * Peek an sk_buff. Unlike most other operations you _MUST_
+ * Peek an &sk_buff. Unlike most other operations you _MUST_
* be careful with this one. A peek leaves the buffer on the
* list and someone else may run off with it. You must hold
* the appropriate locks or have a private queue to do this.
*
- * Returns NULL for an empty list or a pointer to the tail element.
+ * Returns %NULL for an empty list or a pointer to the tail element.
* The reference count is not incremented and the reference is therefore
* volatile. Use with caution.
*/
@@ -391,7 +391,7 @@
* skb_queue_len - get queue length
* @list_: list to measure
*
- * Return the length of an sk_buff queue.
+ * Return the length of an &sk_buff queue.
*/
extern __inline__ __u32 skb_queue_len(struct sk_buff_head *list_)
@@ -446,7 +446,7 @@
* @newsk: buffer to queue
*
* Queue a buffer at the start of the list. This function takes the
- * list lock and can be used safely with other locking sk_buff functions
+ * list lock and can be used safely with other locking &sk_buff functions
* safely.
*
* A buffer cannot be placed on two lists at the same time.
@@ -493,7 +493,7 @@
* @newsk: buffer to queue
*
* Queue a buffer at the tail of the list. This function takes the
- * list lock and can be used safely with other locking sk_buff functions
+ * list lock and can be used safely with other locking &sk_buff functions
* safely.
*
* A buffer cannot be placed on two lists at the same time.
@@ -514,7 +514,7 @@
*
* Remove the head of the list. This function does not take any locks
* so must be used with appropriate locks held only. The head item is
- * returned or NULL if the list is empty.
+ * returned or %NULL if the list is empty.
*/
extern __inline__ struct sk_buff *__skb_dequeue(struct sk_buff_head *list)
@@ -543,7 +543,7 @@
*
* Remove the head of the list. The list lock is taken so the function
* may be used safely with other locking list functions. The head item is
- * returned or NULL if the list is empty.
+ * returned or %NULL if the list is empty.
*/
extern __inline__ struct sk_buff *skb_dequeue(struct sk_buff_head *list)
@@ -675,7 +675,7 @@
*
* Remove the tail of the list. This function does not take any locks
* so must be used with appropriate locks held only. The tail item is
- * returned or NULL if the list is empty.
+ * returned or %NULL if the list is empty.
*/
extern __inline__ struct sk_buff *__skb_dequeue_tail(struct sk_buff_head *list)
@@ -692,7 +692,7 @@
*
* Remove the head of the list. The list lock is taken so the function
* may be used safely with other locking list functions. The tail item is
- * returned or NULL if the list is empty.
+ * returned or %NULL if the list is empty.
*/
extern __inline__ struct sk_buff *skb_dequeue_tail(struct sk_buff_head *list)
@@ -725,7 +725,7 @@
*
* This function extends the used data area of the buffer. If this would
* exceed the total buffer size the kernel will panic. A pointer to the
- * first byte of the extra data is returned
+ * first byte of the extra data is returned.
*/
extern __inline__ unsigned char *skb_put(struct sk_buff *skb, unsigned int len)
@@ -752,8 +752,8 @@
* @len: amount of data to add
*
* This function extends the used data area of the buffer at the buffer
- * start. If this would exceed the total buffer headroom the kernel will
- * panic. A pointer to the first byte of the extra data is returned
+ * start. If this would exceed the total buffer headroom the kernel will
+ * panic. A pointer to the first byte of the extra data is returned.
*/
extern __inline__ unsigned char *skb_push(struct sk_buff *skb, unsigned int len)
@@ -777,10 +777,10 @@
* @skb: buffer to use
* @len: amount of data to remove
*
- * This function removes data from the start of a buffer, returning
+ * This function removes data from the start of a buffer, returning
* the memory to the headroom. A pointer to the next data in the buffer
* is returned. Once the data has been pulled future pushes will overwrite
- * the old data
+ * the old data.
*/
extern __inline__ unsigned char * skb_pull(struct sk_buff *skb, unsigned int len)
@@ -794,7 +794,7 @@
* skb_headroom - bytes at buffer head
* @skb: buffer to check
*
- * Return the number of bytes of free space at the head of an sk_buff
+ * Return the number of bytes of free space at the head of an &sk_buff.
*/
extern __inline__ int skb_headroom(const struct sk_buff *skb)
@@ -819,7 +819,7 @@
* @skb: buffer to alter
* @len: bytes to move
*
- * Increase the headroom of an empty sk_buff by reducing the tail
+ * Increase the headroom of an empty &sk_buff by reducing the tail
* room. This is only allowed for an empty buffer.
*/
@@ -856,8 +856,8 @@
* skb_orphan - orphan a buffer
* @skb: buffer to orphan
*
- * If a buffer currently has an owner then we call the owners
- * destructor function and make the skb unowned. The buffer continues
+ * If a buffer currently has an owner then we call the owner's
+ * destructor function and make the @skb unowned. The buffer continues
* to exist but is no longer charged to its former owner.
*/
@@ -874,7 +874,7 @@
* skb_purge - empty a list
* @list: list to empty
*
- * Delete all buffers on an sk_buff list. Each buffer is removed from
+ * Delete all buffers on an &sk_buff list. Each buffer is removed from
* the list and one reference dropped. This function takes the list
* lock and is atomic with respect to other list locking functions.
*/
@@ -891,7 +891,7 @@
* __skb_purge - empty a list
* @list: list to empty
*
- * Delete all buffers on an sk_buff list. Each buffer is removed from
+ * Delete all buffers on an &sk_buff list. Each buffer is removed from
* the list and one reference dropped. This function does not take the
* list lock and the caller must hold the relevant locks to use it.
*/
@@ -908,12 +908,12 @@
* dev_alloc_skb - allocate an skbuff for sending
* @length: length to allocate
*
- * Allocate a new sk_buff and assign it a usage count of one. The
+ * Allocate a new &sk_buff and assign it a usage count of one. The
* buffer has unspecified headroom built in. Users should allocate
* the headroom they think they need without accounting for the
* built in space. The built in space is used for optimisations.
*
- * NULL is returned in there is no free memory. Although this function
+ * %NULL is returned in there is no free memory. Although this function
* allocates memory it can be called from an interrupt.
*/
@@ -934,7 +934,7 @@
*
* If the buffer passed lacks sufficient headroom or is a clone then
* it is copied and the additional headroom made available. If there
- * is no free memory NULL is returned. The new buffer is returned if
+ * is no free memory %NULL is returned. The new buffer is returned if
* a copy was made (and the old one dropped a reference). The existing
* buffer is returned otherwise.
*
diff -durN linux-2.3.99-pre4-4/kernel/pm.c linux/kernel/pm.c
--- linux-2.3.99-pre4-4/kernel/pm.c Fri Mar 17 18:35:28 2000
+++ linux/kernel/pm.c Wed Apr 5 21:50:48 2000
@@ -30,13 +30,13 @@
/**
* pm_register - register a device with power management
- * @type: The device type
- * @id: Device ID
- * @callback: Callback function
+ * @type: device type
+ * @id: device ID
+ * @callback: callback function
*
* Add a device to the list of devices that wish to be notified about
- * power management events. A pm_dev structure is returnd on success,
- * on failure the return is NULL
+ * power management events. A &pm_dev structure is returned on success,
+ * on failure the return is %NULL.
*/
struct pm_dev *pm_register(pm_dev_t type,
@@ -113,8 +113,8 @@
* @data: data for the callback
*
* Issue a power management request to a given device. The
- * PM_SUSPEND and PM_RESUME events are handled specially. The
- * data field must hold the intented next state. No call is made
+ * %PM_SUSPEND and %PM_RESUME events are handled specially. The
+ * data field must hold the intended next state. No call is made
* if the state matches.
*
* BUGS: what stops two power management requests occuring in parallel
@@ -171,12 +171,12 @@
}
/**
- * pm_send - send request to all managed device
+ * pm_send_all - send request to all managed devices
* @rqst: power management request
* @data: data for the callback
*
* Issue a power management request to a all devices. The
- * PM_SUSPEND events are handled specially. Any device is
+ * %PM_SUSPEND events are handled specially. Any device is
* permitted to fail a suspend by returning a non zero (error)
* value from its callback function. If any device vetoes a
* suspend request then all other devices that have suspended
@@ -214,14 +214,14 @@
/**
* pm_find - find a device
* @type: type of device
- * @from: Where to start looking
+ * @from: where to start looking
*
* Scan the power management list for devices of a specific type. The
* return value for a matching device may be passed to further calls
- * to this function to find further matches. A NULL indicates the end
+ * to this function to find further matches. A %NULL indicates the end
* of the list.
*
- * To search from the beginning pass NULL as the from value.
+ * To search from the beginning pass %NULL as the @from value.
*/
struct pm_dev *pm_find(pm_dev_t type, struct pm_dev *from)
diff -durN linux-2.3.99-pre4-4/net/core/dev.c linux/net/core/dev.c
--- linux-2.3.99-pre4-4/net/core/dev.c Wed Apr 5 16:45:55 2000
+++ linux/net/core/dev.c Wed Apr 5 21:37:57 2000
@@ -181,7 +181,7 @@
* dev_add_pack - add packet handler
* @pt: packet type declaration
*
- * Add a protocol handler to the networking stack. The passed packet_type
+ * Add a protocol handler to the networking stack. The passed &packet_type
* is linked into kernel lists and may not be freed until it has been
* removed from the kernel lists.
*/
@@ -217,7 +217,7 @@
* @pt: packet type declaration
*
* Remove a protocol handler that was previously added to the kernel
- * protocol handlers by dev_add_pack. The passed packet_type is removed
+ * protocol handlers by dev_add_pack(). The passed &packet_type is removed
* from the kernel lists and can be freed or reused once this function
* returns.
*/
@@ -260,9 +260,9 @@
* __dev_get_by_name - find a device by its name
* @name: name to find
*
- * Find an interface by name. Must be called under rtnl semaphore
- * or dev_base_lock. If the name is found a pointer to the device
- * is returned. If the name is not found then NULL is returned. The
+ * Find an interface by name. Must be called under RTNL semaphore
+ * or @dev_base_lock. If the name is found a pointer to the device
+ * is returned. If the name is not found then %NULL is returned. The
* reference counters are not incremented so the caller must be
* careful with locks.
*/
@@ -286,7 +286,7 @@
* Find an interface by name. This can be called from any
* context and does its own locking. The returned handle has
* the usage count incremented and the caller must use dev_put() to
- * release it when it is no longer needed. NULL is returned if no
+ * release it when it is no longer needed. %NULL is returned if no
* matching device is found.
*/
@@ -336,11 +336,11 @@
* __dev_get_by_index - find a device by its ifindex
* @ifindex: index of device
*
- * Search for an interface by index. Returns NULL if the device
+ * Search for an interface by index. Returns %NULL if the device
* is not found or a pointer to the device. The device has not
* had its reference counter increased so the caller must be careful
- * about locking. The caller must hold either the rtnl semaphore
- * or dev_base_lock.
+ * about locking. The caller must hold either the RTNL semaphore
+ * or @dev_base_lock.
*/
struct net_device * __dev_get_by_index(int ifindex)
@@ -440,15 +440,15 @@
* @name: name format string
* @err: error return pointer
*
- * Passed a format string - eg "lt%d" it will allocate a network device
- * and space for the name. NULL is returned if no memory is available.
+ * Passed a format string, eg. "lt%d", it will allocate a network device
+ * and space for the name. %NULL is returned if no memory is available.
* If the allocation succeeds then the name is assigned and the
- * device pointer returned. NULL is returned if the name allocation failed.
- * The cause of an error is returned as a negative errno code in the
- * variable err points to.
+ * device pointer returned. %NULL is returned if the name allocation
+ * failed. The cause of an error is returned as a negative errno code
+ * in the variable @err points to.
*
- * The claler must hold the dev_base or rtnl locks when doing this in order
- * to avoid duplicate name allocations.
+ * The caller must hold the @dev_base or RTNL locks when doing this in
+ * order to avoid duplicate name allocations.
*/
struct net_device *dev_alloc(const char *name, int *err)
@@ -520,9 +520,9 @@
* dev_open - prepare an interface for use.
* @dev: device to open
*
- * Takes a device from down to up state. The devices private open
+ * Takes a device from down to up state. The device's private open
* function is invoked and then the multicast lists are loaded. Finally
- * the device is moved into the up state and a NETDEV_UP message is
+ * the device is moved into the up state and a %NETDEV_UP message is
* sent to the netdev notifier chain.
*
* Calling this function on an active interface is a nop. On a failure
@@ -622,8 +622,8 @@
* @dev: device to shutdown
*
* This function moves an active device into down state. A
- * NETDEV_GOING_DOWN is sent to the netev notifier chain. The device
- * is then deactivated and finally a NETDEV_DOWN is sent to the notifier
+ * %NETDEV_GOING_DOWN is sent to the netdev notifier chain. The device
+ * is then deactivated and finally a %NETDEV_DOWN is sent to the notifier
* chain.
*/
@@ -695,9 +695,10 @@
* unregister_netdevice_notifier - unregister a network notifier block
* @nb: notifier
*
- * Unregister a notifier previously registered by register_netdevice_notifier
- * The notifier is unlinked into the kernel structures and may
- * then be reused. A negative errno code is returned on a failure.
+ * Unregister a notifier previously registered by
+ * register_netdevice_notifier(). The notifier is unlinked into the
+ * kernel structures and may then be reused. A negative errno code
+ * is returned on a failure.
*/
int unregister_netdevice_notifier(struct notifier_block *nb)
@@ -1079,7 +1080,7 @@
* @fn: function to call
*
* Make a function call that is atomic with respect to the protocol
- * layers
+ * layers.
*/
void net_call_rx_atomic(void (*fn)(void))
@@ -1554,10 +1555,10 @@
* @slave: slave device
* @master: new master device
*
- * Changes the master device of the slave. Pass NULL to break the
+ * Changes the master device of the slave. Pass %NULL to break the
* bonding. The caller must hold the RTNL semaphore. On a failure
* a negative errno code is returned. On success the reference counts
- * are adjusted, RTM_NEWLINK is sent to the routing socket and the
+ * are adjusted, %RTM_NEWLINK is sent to the routing socket and the
* function returns zero.
*/
@@ -1629,7 +1630,7 @@
* Add or remove reception of all multicast frames to a device. While the
* count in the device remains above zero the interface remains listening
* to all interfaces. Once it hits zero the device reverts back to normal
- * filtering operation. A negative inc value is used to drop the counter
+ * filtering operation. A negative @inc value is used to drop the counter
* when releasing a resource needing all multicasts.
*/
@@ -2051,7 +2052,7 @@
* @dev: device to register
*
* Take a completed network device structure and add it to the kernel
- * interfaces. A NETDEV_REGISTER message is sent to the netdev notifier
+ * interfaces. A %NETDEV_REGISTER message is sent to the netdev notifier
* chain. 0 is returned on success. A negative errno code is returned
* on a failure to set up the device, or if the name is a duplicate.
*
diff -durN linux-2.3.99-pre4-4/net/core/skbuff.c linux/net/core/skbuff.c
--- linux-2.3.99-pre4-4/net/core/skbuff.c Wed Apr 5 16:45:55 2000
+++ linux/net/core/skbuff.c Wed Apr 5 21:30:42 2000
@@ -83,7 +83,7 @@
* @sz: size
* @here: address
*
- * Out of line support code for skb_put. Not user callable
+ * Out of line support code for skb_put(). Not user callable.
*/
void skb_over_panic(struct sk_buff *skb, int sz, void *here)
@@ -99,7 +99,7 @@
* @sz: size
* @here: address
*
- * Out of line support code for skb_push. Not user callable
+ * Out of line support code for skb_push(). Not user callable.
*/
@@ -154,12 +154,12 @@
* @size: size to allocate
* @gfp_mask: allocation mask
*
- * Allocate a new sk_buff. The returned buffer has no headroom and a
+ * Allocate a new &sk_buff. The returned buffer has no headroom and a
* tail room of size bytes. The object has a reference count of one.
- * The return is the buffer. On a failure the return is NULL.
+ * The return is the buffer. On a failure the return is %NULL.
*
- * Buffers may only be allocated from interrupts using a gfp_mask of
- * GFP_ATOMIC.
+ * Buffers may only be allocated from interrupts using a @gfp_mask of
+ * %GFP_ATOMIC.
*/
struct sk_buff *alloc_skb(unsigned int size,int gfp_mask)
@@ -300,13 +300,13 @@
* @skb: buffer to clone
* @gfp_mask: allocation priority
*
- * Duplicate an sk_buff. The new one is not owned by a socket. Both
+ * Duplicate an &sk_buff. The new one is not owned by a socket. Both
* copies share the same packet data but not structure. The new
* buffer has a reference count of 1. If the allocation fails the
- * function returns NULL otherwise the new buffer is returned.
+ * function returns %NULL otherwise the new buffer is returned.
*
- * If this function is called from an interrupt gfp_mask must be
- * GFP_ATOMIC.
+ * If this function is called from an interrupt gfp_mask() must be
+ * %GFP_ATOMIC.
*/
struct sk_buff *skb_clone(struct sk_buff *skb, int gfp_mask)
@@ -383,12 +383,12 @@
* @skb: buffer to copy
* @gfp_mask: allocation priority
*
- * Make a copy of both an sk_buff and its data. This is used when the
+ * Make a copy of both an &sk_buff and its data. This is used when the
* caller wishes to modify the data and needs a private copy of the
- * data to alter. Returns NULL on failure or the pointer to the buffer
+ * data to alter. Returns %NULL on failure or the pointer to the buffer
* on success. The returned buffer has a reference count of 1.
*
- * You must pass GFP_ATOMIC as the allocation priority if this function
+ * You must pass %GFP_ATOMIC as the allocation priority if this function
* is called from an interrupt.
*/
@@ -423,15 +423,15 @@
* @newtailroom: new free bytes at tail
* @gfp_mask: allocation priority
*
- * Make a copy of both an sk_buff and its data and while doing so
+ * Make a copy of both an &sk_buff and its data and while doing so
* allocate additional space.
*
* This is used when the caller wishes to modify the data and needs a
* private copy of the data to alter as well as more space for new fields.
- * Returns NULL on failure or the pointer to the buffer
+ * Returns %NULL on failure or the pointer to the buffer
* on success. The returned buffer has a reference count of 1.
*
- * You must pass GFP_ATOMIC as the allocation priority if this function
+ * You must pass %GFP_ATOMIC as the allocation priority if this function
* is called from an interrupt.
*/
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.rutgers.edu
Please read the FAQ at http://www.tux.org/lkml/
This archive was generated by hypermail 2b29 : Fri Apr 07 2000 - 21:00:15 EST