ipc: standardize code comments

IPC commenting style is all over the place, *specially* in util.c.  This
patch orders things a bit.

Signed-off-by: Davidlohr Bueso <davidlohr@hp.com>
Cc: Aswin Chandramouleeswaran <aswin@hp.com>
Cc: Rik van Riel <riel@redhat.com>
Acked-by: Manfred Spraul <manfred@colorfullife.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

ipc/sem.c

@@ -225,7 +225,7 @@ static void unmerge_queues(struct sem_array *sma)
 }
 
 /**
- * merge_queues - Merge single semop queues into global queue
+ * merge_queues - merge single semop queues into global queue
  * @sma: semaphore array
  *
  * This function merges all per-semaphore queues into the global queue.
@@ -474,7 +474,6 @@ static inline void sem_rmid(struct ipc_namespace *ns, struct sem_array *s)
  *
  * Called with sem_ids.rwsem held (as a writer)
  */
-
 static int newary(struct ipc_namespace *ns, struct ipc_params *params)
 {
 	int id;
@@ -682,7 +681,7 @@ static void wake_up_sem_queue_prepare(struct list_head *pt,
 }
 
 /**
- * wake_up_sem_queue_do(pt) - do the actual wake-up
+ * wake_up_sem_queue_do - do the actual wake-up
  * @pt: list of tasks to be woken up
  *
  * Do the actual wake-up.
@@ -748,7 +747,7 @@ static int check_restart(struct sem_array *sma, struct sem_queue *q)
 }
 
 /**
- * wake_const_ops(sma, semnum, pt) - Wake up non-alter tasks
+ * wake_const_ops - wake up non-alter tasks
  * @sma: semaphore array.
  * @semnum: semaphore that was modified.
  * @pt: list head for the tasks that must be woken up.
@@ -798,15 +797,14 @@ static int wake_const_ops(struct sem_array *sma, int semnum,
 }
 
 /**
- * do_smart_wakeup_zero(sma, sops, nsops, pt) - wakeup all wait for zero tasks
+ * do_smart_wakeup_zero - wakeup all wait for zero tasks
  * @sma: semaphore array
  * @sops: operations that were performed
  * @nsops: number of operations
  * @pt: list head of the tasks that must be woken up.
  *
- * do_smart_wakeup_zero() checks all required queue for wait-for-zero
+ * Checks all required queue for wait-for-zero operations, based
- * operations, based on the actual changes that were performed on the
+ * on the actual changes that were performed on the semaphore array.
- * semaphore array.
  * The function returns 1 if at least one operation was completed successfully.
  */
 static int do_smart_wakeup_zero(struct sem_array *sma, struct sembuf *sops,
@@ -850,7 +848,7 @@ static int do_smart_wakeup_zero(struct sem_array *sma, struct sembuf *sops,
 
 
 /**
- * update_queue(sma, semnum): Look for tasks that can be completed.
+ * update_queue - look for tasks that can be completed.
  * @sma: semaphore array.
  * @semnum: semaphore that was modified.
  * @pt: list head for the tasks that must be woken up.
@@ -920,7 +918,7 @@ again:
 }
 
 /**
- * set_semotime(sma, sops) - set sem_otime
+ * set_semotime - set sem_otime
  * @sma: semaphore array
  * @sops: operations that modified the array, may be NULL
  *
@@ -938,7 +936,7 @@ static void set_semotime(struct sem_array *sma, struct sembuf *sops)
 }
 
 /**
- * do_smart_update(sma, sops, nsops, otime, pt) - optimized update_queue
+ * do_smart_update - optimized update_queue
  * @sma: semaphore array
  * @sops: operations that were performed
  * @nsops: number of operations
@@ -1647,7 +1645,7 @@ static struct sem_undo *lookup_undo(struct sem_undo_list *ulp, int semid)
 }
 
 /**
- * find_alloc_undo - Lookup (and if not present create) undo array
+ * find_alloc_undo - lookup (and if not present create) undo array
  * @ns: namespace
  * @semid: semaphore array id
  *
@@ -1737,7 +1735,7 @@ out:
 
 
 /**
- * get_queue_result - Retrieve the result code from sem_queue
+ * get_queue_result - retrieve the result code from sem_queue
  * @q: Pointer to queue structure
  *
  * Retrieve the return code from the pending queue. If IN_WAKEUP is found in

ipc/shm.c

@@ -477,7 +477,6 @@ static const struct vm_operations_struct shm_vm_ops = {
  *
  * Called with shm_ids.rwsem held as a writer.
  */
-
 static int newseg(struct ipc_namespace *ns, struct ipc_params *params)
 {
 	key_t key = params->key;

ipc/util.c

@@ -110,15 +110,15 @@ static struct notifier_block ipc_memory_nb = {
 };
 
 /**
- *	ipc_init	-	initialise IPC subsystem
+ * ipc_init - initialise ipc subsystem
+ *
+ * The various sysv ipc resources (semaphores, messages and shared
+ * memory) are initialised.
  *
- *	The various system5 IPC resources (semaphores, messages and shared
- *	memory) are initialised
  * A callback routine is registered into the memory hotplug notifier
  * chain: since msgmni scales to lowmem this callback routine will be
  * called upon successful memory add / remove to recompute msmgni.
  */
- 
 static int __init ipc_init(void)
 {
 	sem_init();
@@ -131,13 +131,12 @@ static int __init ipc_init(void)
 __initcall(ipc_init);
 
 /**
- *	ipc_init_ids		-	initialise IPC identifiers
+ * ipc_init_ids	- initialise ipc identifiers
- *	@ids: Identifier set
+ * @ids: ipc identifier set
  *
  * Set up the sequence range to use for the ipc identifier range (limited
  * below IPCMNI) then initialise the ids idr.
  */
- 
 void ipc_init_ids(struct ipc_ids *ids)
 {
 	init_rwsem(&ids->rwsem);
@@ -159,7 +158,7 @@ void ipc_init_ids(struct ipc_ids *ids)
 #ifdef CONFIG_PROC_FS
 static const struct file_operations sysvipc_proc_fops;
 /**
- *	ipc_init_proc_interface	-  Create a proc interface for sysipc types using a seq_file interface.
+ * ipc_init_proc_interface -  create a proc interface for sysipc types using a seq_file interface.
  * @path: Path in procfs
  * @header: Banner to be printed at the beginning of the file.
  * @ids: ipc id table to iterate.
@@ -192,15 +191,14 @@ void __init ipc_init_proc_interface(const char *path, const char *header,
 
 /**
  * ipc_findkey	- find a key in an ipc identifier set
- *	@ids: Identifier set
+ * @ids: ipc identifier set
- *	@key: The key to find
+ * @key: key to find
  *	
- *	Requires ipc_ids.rwsem locked.
+ * Returns the locked pointer to the ipc structure if found or NULL
- *	Returns the LOCKED pointer to the ipc structure if found or NULL
+ * otherwise. If key is found ipc points to the owning ipc structure
- *	if not.
+ *
- *	If key is found ipc points to the owning ipc structure
+ * Called with ipc_ids.rwsem held.
  */
- 
 static struct kern_ipc_perm *ipc_findkey(struct ipc_ids *ids, key_t key)
 {
 	struct kern_ipc_perm *ipc;
@@ -228,11 +226,10 @@ static struct kern_ipc_perm *ipc_findkey(struct ipc_ids *ids, key_t key)
 
 /**
  * ipc_get_maxid - get the last assigned id
- *	@ids: IPC identifier set
+ * @ids: ipc identifier set
  *
  * Called with ipc_ids.rwsem held.
  */
-
 int ipc_get_maxid(struct ipc_ids *ids)
 {
 	struct kern_ipc_perm *ipc;
@@ -258,12 +255,12 @@ int ipc_get_maxid(struct ipc_ids *ids)
 }
 
 /**
- *	ipc_addid	-	add an IPC identifier
+ * ipc_addid - add an ipc identifier
- *	@ids: IPC identifier set
+ * @ids: ipc identifier set
- *	@new: new IPC permission set
+ * @new: new ipc permission set
  * @size: limit for the number of used ids
  *
- *	Add an entry 'new' to the IPC ids idr. The permissions object is
+ * Add an entry 'new' to the ipc ids idr. The permissions object is
  * initialised and the first free entry is set up and the id assigned
  * is returned. The 'new' entry is returned in a locked state on success.
  * On failure the entry is not locked and a negative err-code is returned.
@@ -321,8 +318,8 @@ int ipc_addid(struct ipc_ids *ids, struct kern_ipc_perm *new, int size)
 
 /**
  * ipcget_new -	create a new ipc object
- *	@ns: namespace
+ * @ns: ipc namespace
- *	@ids: IPC identifer set
+ * @ids: ipc identifer set
  * @ops: the actual creation routine to call
  * @params: its parameters
  *
@@ -341,17 +338,17 @@ static int ipcget_new(struct ipc_namespace *ns, struct ipc_ids *ids,
 }
 
 /**
- *	ipc_check_perms	-	check security and permissions for an IPC
+ * ipc_check_perms - check security and permissions for an ipc object
- *	@ns: IPC namespace
+ * @ns: ipc namespace
  * @ipcp: ipc permission set
  * @ops: the actual security routine to call
  * @params: its parameters
  *
  * This routine is called by sys_msgget(), sys_semget() and sys_shmget()
  * when the key is not IPC_PRIVATE and that key already exists in the
- *      ids IDR.
+ * ds IDR.
  *
- *	On success, the IPC id is returned.
+ * On success, the ipc id is returned.
  *
  * It is called with ipc_ids.rwsem and ipcp->lock held.
  */
@@ -375,8 +372,8 @@ static int ipc_check_perms(struct ipc_namespace *ns,
 
 /**
  * ipcget_public - get an ipc object or create a new one
- *	@ns: namespace
+ * @ns: ipc namespace
- *	@ids: IPC identifer set
+ * @ids: ipc identifer set
  * @ops: the actual creation routine to call
  * @params: its parameters
  *
@@ -431,14 +428,13 @@ static int ipcget_public(struct ipc_namespace *ns, struct ipc_ids *ids,
 
 
 /**
- *	ipc_rmid	-	remove an IPC identifier
+ * ipc_rmid - remove an ipc identifier
- *	@ids: IPC identifier set
+ * @ids: ipc identifier set
  * @ipcp: ipc perm structure containing the identifier to remove
  *
  * ipc_ids.rwsem (as a writer) and the spinlock for this ID are held
  * before this function is called, and remain locked on the exit.
  */
- 
 void ipc_rmid(struct ipc_ids *ids, struct kern_ipc_perm *ipcp)
 {
 	int lid = ipcid_to_idx(ipcp->id);
@@ -459,7 +455,6 @@ void ipc_rmid(struct ipc_ids *ids, struct kern_ipc_perm *ipcp)
  * Allocate memory from the appropriate pools and return a pointer to it.
  * NULL is returned if the allocation fails
  */
- 
 void *ipc_alloc(int size)
 {
 	void *out;
@@ -478,7 +473,6 @@ void *ipc_alloc(int size)
  * Free a block created with ipc_alloc(). The caller must know the size
  * used in the allocation call.
  */
-
 void ipc_free(void *ptr, int size)
 {
 	if (size > PAGE_SIZE)
@@ -534,17 +528,16 @@ void ipc_rcu_free(struct rcu_head *head)
 }
 
 /**
- *	ipcperms	-	check IPC permissions
+ * ipcperms - check ipc permissions
- *	@ns: IPC namespace
+ * @ns: ipc namespace
- *	@ipcp: IPC permission set
+ * @ipcp: ipc permission set
- *	@flag: desired permission set.
+ * @flag: desired permission set
  *
  * Check user, group, other permissions for access
  * to ipc resources. return 0 if allowed
  *
  * @flag will most probably be 0 or S_...UGO from <linux/stat.h>
  */
- 
 int ipcperms(struct ipc_namespace *ns, struct kern_ipc_perm *ipcp, short flag)
 {
 	kuid_t euid = current_euid();
@@ -574,13 +567,11 @@ int ipcperms(struct ipc_namespace *ns, struct kern_ipc_perm *ipcp, short flag)
 /**
  * kernel_to_ipc64_perm	- convert kernel ipc permissions to user
  * @in: kernel permissions
- *	@out: new style IPC permissions
+ * @out: new style ipc permissions
  *
  * Turn the kernel object @in into a set of permissions descriptions
  * for returning to userspace (@out).
  */
- 
-
 void kernel_to_ipc64_perm(struct kern_ipc_perm *in, struct ipc64_perm *out)
 {
 	out->key	= in->key;
@@ -594,13 +585,12 @@ void kernel_to_ipc64_perm(struct kern_ipc_perm *in, struct ipc64_perm *out)
 
 /**
  * ipc64_perm_to_ipc_perm - convert new ipc permissions to old
- *	@in: new style IPC permissions
+ * @in: new style ipc permissions
- *	@out: old style IPC permissions
+ * @out: old style ipc permissions
  *
  * Turn the new style permissions object @in into a compatibility
  * object and store it into the @out pointer.
  */
- 
 void ipc64_perm_to_ipc_perm(struct ipc64_perm *in, struct ipc_perm *out)
 {
 	out->key	= in->key;
@@ -635,8 +625,8 @@ struct kern_ipc_perm *ipc_obtain_object(struct ipc_ids *ids, int id)
 }
 
 /**
- * ipc_lock - Lock an ipc structure without rwsem held
+ * ipc_lock - lock an ipc structure without rwsem held
- * @ids: IPC identifier set
+ * @ids: ipc identifier set
  * @id: ipc id to look for
  *
  * Look for an id in the ipc ids idr and lock the associated ipc object.
@@ -694,7 +684,7 @@ out:
 /**
  * ipcget - Common sys_*get() code
  * @ns: namsepace
- * @ids : IPC identifier set
+ * @ids: ipc identifier set
  * @ops: operations to be called on ipc object creation, permission checks
  *       and further checks
  * @params: the parameters needed by the previous operations.
@@ -711,7 +701,7 @@ int ipcget(struct ipc_namespace *ns, struct ipc_ids *ids,
 }
 
 /**
- * ipc_update_perm - update the permissions of an IPC.
+ * ipc_update_perm - update the permissions of an ipc object
  * @in:  the permission given as input.
  * @out: the permission of the ipc to set.
  */
@@ -732,7 +722,7 @@ int ipc_update_perm(struct ipc64_perm *in, struct kern_ipc_perm *out)
 
 /**
  * ipcctl_pre_down_nolock - retrieve an ipc and check permissions for some IPC_XXX cmd
- * @ns:  the ipc namespace
+ * @ns:  ipc namespace
  * @ids:  the table of ids where to look for the ipc
  * @id:   the id of the ipc to retrieve
  * @cmd:  the cmd to check
@@ -779,14 +769,13 @@ err:
 
 
 /**
- *	ipc_parse_version	-	IPC call version
+ * ipc_parse_version - ipc call version
  * @cmd: pointer to command
  *
  * Return IPC_64 for new style IPC and IPC_OLD for old style IPC.
  * The @cmd value is turned from an encoding command and version into
  * just the command code.
  */
- 
 int ipc_parse_version(int *cmd)
 {
 	if (*cmd & IPC_64) {