[PATCH] fix list.h kernel-doc

kernel-doc: Put all short function descriptions on one line or if they are too long, omit the short description & add a Description: section for them. Change some list iterator descriptions to use "current" point instead of "existing" point. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>

[PATCH] fix list.h kernel-doc
kernel-doc: Put all short function descriptions on one line or if they are too long, omit the short description & add a Description: section for them. Change some list iterator descriptions to use "current" point instead of "existing" point. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Randy Dunlap · Linus Torvalds
1 parent dbf492d6c1
Showing 1 changed file with 52 additions and 30 deletions Side-by-side Diff
include/linux/list.h
@@ -281,16 +281,17 @@
 }
  
 /**
- * list_empty_careful - tests whether a list is
- * empty _and_ checks that no other CPU might be
- * in the process of still modifying either member
+ * list_empty_careful - tests whether a list is empty and not being modified
+ * @head: the list to test
  *
+ * Description:
+ * tests whether a list is empty _and_ checks that no other CPU might be
+ * in the process of modifying either member (next or prev)
+ *
  * NOTE: using list_empty_careful() without synchronization
  * can only be safe if the only activity that can happen
  * to the list entry is list_del_init(). Eg. it cannot be used
  * if another CPU could re-list_add() it.
- *
- * @head: the list to test.
  */
 static inline int list_empty_careful(const struct list_head *head)
 {
@@ -380,7 +381,7 @@
         	pos = pos->prev)
  
 /**
- * list_for_each_safe	-	iterate over a list safe against removal of list entry
+ * list_for_each_safe - iterate over a list safe against removal of list entry
  * @pos:	the &struct list_head to use as a loop counter.
  * @n:		another &struct list_head to use as temporary storage
  * @head:	the head for your list.
  
  
  
@@ -412,21 +413,24 @@
 	     pos = list_entry(pos->member.prev, typeof(*pos), member))
  
 /**
- * list_prepare_entry - prepare a pos entry for use as a start point in
- *			list_for_each_entry_continue
+ * list_prepare_entry - prepare a pos entry for use in list_for_each_entry_continue
  * @pos:	the type * to use as a start point
  * @head:	the head of the list
  * @member:	the name of the list_struct within the struct.
+ *
+ * Prepares a pos entry for use as a start point in list_for_each_entry_continue.
  */
 #define list_prepare_entry(pos, head, member) \
 	((pos) ? : list_entry(head, typeof(*pos), member))
  
 /**
- * list_for_each_entry_continue -	iterate over list of given type
- *			continuing after existing point
+ * list_for_each_entry_continue - continue iteration over list of given type
  * @pos:	the type * to use as a loop counter.
  * @head:	the head for your list.
  * @member:	the name of the list_struct within the struct.
+ *
+ * Continue to iterate over list of given type, continuing after
+ * the current position.
  */
 #define list_for_each_entry_continue(pos, head, member) 		\
 	for (pos = list_entry(pos->member.next, typeof(*pos), member);	\
  
@@ -434,11 +438,12 @@
 	     pos = list_entry(pos->member.next, typeof(*pos), member))
  
 /**
- * list_for_each_entry_from -	iterate over list of given type
- *			continuing from existing point
+ * list_for_each_entry_from - iterate over list of given type from the current point
  * @pos:	the type * to use as a loop counter.
  * @head:	the head for your list.
  * @member:	the name of the list_struct within the struct.
+ *
+ * Iterate over list of given type, continuing from current position.
  */
 #define list_for_each_entry_from(pos, head, member) 			\
 	for (; prefetch(pos->member.next), &pos->member != (head);	\
  
@@ -458,12 +463,14 @@
 	     pos = n, n = list_entry(n->member.next, typeof(*n), member))
  
 /**
- * list_for_each_entry_safe_continue -	iterate over list of given type
- *			continuing after existing point safe against removal of list entry
+ * list_for_each_entry_safe_continue
  * @pos:	the type * to use as a loop counter.
  * @n:		another type * to use as temporary storage
  * @head:	the head for your list.
  * @member:	the name of the list_struct within the struct.
+ *
+ * Iterate over list of given type, continuing after current point,
+ * safe against removal of list entry.
  */
 #define list_for_each_entry_safe_continue(pos, n, head, member) 		\
 	for (pos = list_entry(pos->member.next, typeof(*pos), member), 		\
  
@@ -472,12 +479,14 @@
 	     pos = n, n = list_entry(n->member.next, typeof(*n), member))
  
 /**
- * list_for_each_entry_safe_from - iterate over list of given type
- *			from existing point safe against removal of list entry
+ * list_for_each_entry_safe_from
  * @pos:	the type * to use as a loop counter.
  * @n:		another type * to use as temporary storage
  * @head:	the head for your list.
  * @member:	the name of the list_struct within the struct.
+ *
+ * Iterate over list of given type from current point, safe against
+ * removal of list entry.
  */
 #define list_for_each_entry_safe_from(pos, n, head, member) 			\
 	for (n = list_entry(pos->member.next, typeof(*pos), member);		\
  
@@ -485,12 +494,14 @@
 	     pos = n, n = list_entry(n->member.next, typeof(*n), member))
  
 /**
- * list_for_each_entry_safe_reverse - iterate backwards over list of given type safe against
- *				      removal of list entry
+ * list_for_each_entry_safe_reverse
  * @pos:	the type * to use as a loop counter.
  * @n:		another type * to use as temporary storage
  * @head:	the head for your list.
  * @member:	the name of the list_struct within the struct.
+ *
+ * Iterate backwards over list of given type, safe against removal
+ * of list entry.
  */
 #define list_for_each_entry_safe_reverse(pos, n, head, member)		\
 	for (pos = list_entry((head)->prev, typeof(*pos), member),	\
  
@@ -518,12 +529,13 @@
         	pos = pos->next)
  
 /**
- * list_for_each_safe_rcu	-	iterate over an rcu-protected list safe
- *					against removal of list entry
+ * list_for_each_safe_rcu
  * @pos:	the &struct list_head to use as a loop counter.
  * @n:		another &struct list_head to use as temporary storage
  * @head:	the head for your list.
  *
+ * Iterate over an rcu-protected list, safe against removal of list entry.
+ *
  * This list-traversal primitive may safely run concurrently with
  * the _rcu list-mutation primitives such as list_add_rcu()
  * as long as the traversal is guarded by rcu_read_lock().
  
@@ -551,11 +563,12 @@
  
  
 /**
- * list_for_each_continue_rcu	-	iterate over an rcu-protected list
- *			continuing after existing point.
+ * list_for_each_continue_rcu
  * @pos:	the &struct list_head to use as a loop counter.
  * @head:	the head for your list.
  *
+ * Iterate over an rcu-protected list, continuing after current point.
+ *
  * This list-traversal primitive may safely run concurrently with
  * the _rcu list-mutation primitives such as list_add_rcu()
  * as long as the traversal is guarded by rcu_read_lock().
  
@@ -681,11 +694,14 @@
  
  
 /**
- * hlist_add_head_rcu - adds the specified element to the specified hlist,
- * while permitting racing traversals.
+ * hlist_add_head_rcu
  * @n: the element to add to the hash list.
  * @h: the list to add to.
  *
+ * Description:
+ * Adds the specified element to the specified hlist,
+ * while permitting racing traversals.
+ *
  * The caller must take whatever precautions are necessary
  * (such as holding appropriate locks) to avoid racing
  * with another list-mutation primitive, such as hlist_add_head_rcu()
  
@@ -730,11 +746,14 @@
 }
  
 /**
- * hlist_add_before_rcu - adds the specified element to the specified hlist
- * before the specified node while permitting racing traversals.
+ * hlist_add_before_rcu
  * @n: the new element to add to the hash list.
  * @next: the existing element to add the new element before.
  *
+ * Description:
+ * Adds the specified element to the specified hlist
+ * before the specified node while permitting racing traversals.
+ *
  * The caller must take whatever precautions are necessary
  * (such as holding appropriate locks) to avoid racing
  * with another list-mutation primitive, such as hlist_add_head_rcu()
  
@@ -755,11 +774,14 @@
 }
  
 /**
- * hlist_add_after_rcu - adds the specified element to the specified hlist
- * after the specified node while permitting racing traversals.
+ * hlist_add_after_rcu
  * @prev: the existing element to add the new element after.
  * @n: the new element to add to the hash list.
  *
+ * Description:
+ * Adds the specified element to the specified hlist
+ * after the specified node while permitting racing traversals.
+ *
  * The caller must take whatever precautions are necessary
  * (such as holding appropriate locks) to avoid racing
  * with another list-mutation primitive, such as hlist_add_head_rcu()
@@ -804,7 +826,7 @@
 	     pos = pos->next)
  
 /**
- * hlist_for_each_entry_continue - iterate over a hlist continuing after existing point
+ * hlist_for_each_entry_continue - iterate over a hlist continuing after current point
  * @tpos:	the type * to use as a loop counter.
  * @pos:	the &struct hlist_node to use as a loop counter.
  * @member:	the name of the hlist_node within the struct.
@@ -816,7 +838,7 @@
 	     pos = pos->next)
  
 /**
- * hlist_for_each_entry_from - iterate over a hlist continuing from existing point
+ * hlist_for_each_entry_from - iterate over a hlist continuing from current point
  * @tpos:	the type * to use as a loop counter.
  * @pos:	the &struct hlist_node to use as a loop counter.
  * @member:	the name of the hlist_node within the struct.
...	...	@@ -281,16 +281,17 @@
281	281	}
282	282
283	283	/**
284		- * list_empty_careful - tests whether a list is
285		- * empty _and_ checks that no other CPU might be
286		- * in the process of still modifying either member
	284	+ * list_empty_careful - tests whether a list is empty and not being modified
	285	+ * @head: the list to test
287	286	*
	287	+ * Description:
	288	+ * tests whether a list is empty _and_ checks that no other CPU might be
	289	+ * in the process of modifying either member (next or prev)
	290	+ *
288	291	* NOTE: using list_empty_careful() without synchronization
289	292	* can only be safe if the only activity that can happen
290	293	* to the list entry is list_del_init(). Eg. it cannot be used
291	294	* if another CPU could re-list_add() it.
292		- *
293		- * @head: the list to test.
294	295	*/
295	296	static inline int list_empty_careful(const struct list_head *head)
296	297	{
...	...	@@ -380,7 +381,7 @@
380	381	pos = pos->prev)
381	382
382	383	/**
383		- * list_for_each_safe - iterate over a list safe against removal of list entry
	384	+ * list_for_each_safe - iterate over a list safe against removal of list entry
384	385	* @pos: the &struct list_head to use as a loop counter.
385	386	* @n: another &struct list_head to use as temporary storage
386	387	* @head: the head for your list.
387	388
388	389
389	390
...	...	@@ -412,21 +413,24 @@
412	413	pos = list_entry(pos->member.prev, typeof(*pos), member))
413	414
414	415	/**
415		- * list_prepare_entry - prepare a pos entry for use as a start point in
416		- * list_for_each_entry_continue
	416	+ * list_prepare_entry - prepare a pos entry for use in list_for_each_entry_continue
417	417	* @pos: the type * to use as a start point
418	418	* @head: the head of the list
419	419	* @member: the name of the list_struct within the struct.
	420	+ *
	421	+ * Prepares a pos entry for use as a start point in list_for_each_entry_continue.
420	422	*/
421	423	#define list_prepare_entry(pos, head, member) \
422	424	((pos) ? : list_entry(head, typeof(*pos), member))
423	425
424	426	/**
425		- * list_for_each_entry_continue - iterate over list of given type
426		- * continuing after existing point
	427	+ * list_for_each_entry_continue - continue iteration over list of given type
427	428	* @pos: the type * to use as a loop counter.
428	429	* @head: the head for your list.
429	430	* @member: the name of the list_struct within the struct.
	431	+ *
	432	+ * Continue to iterate over list of given type, continuing after
	433	+ * the current position.
430	434	*/
431	435	#define list_for_each_entry_continue(pos, head, member) \
432	436	for (pos = list_entry(pos->member.next, typeof(*pos), member); \
433	437
...	...	@@ -434,11 +438,12 @@
434	438	pos = list_entry(pos->member.next, typeof(*pos), member))
435	439
436	440	/**
437		- * list_for_each_entry_from - iterate over list of given type
438		- * continuing from existing point
	441	+ * list_for_each_entry_from - iterate over list of given type from the current point
439	442	* @pos: the type * to use as a loop counter.
440	443	* @head: the head for your list.
441	444	* @member: the name of the list_struct within the struct.
	445	+ *
	446	+ * Iterate over list of given type, continuing from current position.
442	447	*/
443	448	#define list_for_each_entry_from(pos, head, member) \
444	449	for (; prefetch(pos->member.next), &pos->member != (head); \
445	450
...	...	@@ -458,12 +463,14 @@
458	463	pos = n, n = list_entry(n->member.next, typeof(*n), member))
459	464
460	465	/**
461		- * list_for_each_entry_safe_continue - iterate over list of given type
462		- * continuing after existing point safe against removal of list entry
	466	+ * list_for_each_entry_safe_continue
463	467	* @pos: the type * to use as a loop counter.
464	468	* @n: another type * to use as temporary storage
465	469	* @head: the head for your list.
466	470	* @member: the name of the list_struct within the struct.
	471	+ *
	472	+ * Iterate over list of given type, continuing after current point,
	473	+ * safe against removal of list entry.
467	474	*/
468	475	#define list_for_each_entry_safe_continue(pos, n, head, member) \
469	476	for (pos = list_entry(pos->member.next, typeof(*pos), member), \
470	477
...	...	@@ -472,12 +479,14 @@
472	479	pos = n, n = list_entry(n->member.next, typeof(*n), member))
473	480
474	481	/**
475		- * list_for_each_entry_safe_from - iterate over list of given type
476		- * from existing point safe against removal of list entry
	482	+ * list_for_each_entry_safe_from
477	483	* @pos: the type * to use as a loop counter.
478	484	* @n: another type * to use as temporary storage
479	485	* @head: the head for your list.
480	486	* @member: the name of the list_struct within the struct.
	487	+ *
	488	+ * Iterate over list of given type from current point, safe against
	489	+ * removal of list entry.
481	490	*/
482	491	#define list_for_each_entry_safe_from(pos, n, head, member) \
483	492	for (n = list_entry(pos->member.next, typeof(*pos), member); \
484	493
...	...	@@ -485,12 +494,14 @@
485	494	pos = n, n = list_entry(n->member.next, typeof(*n), member))
486	495
487	496	/**
488		- * list_for_each_entry_safe_reverse - iterate backwards over list of given type safe against
489		- * removal of list entry
	497	+ * list_for_each_entry_safe_reverse
490	498	* @pos: the type * to use as a loop counter.
491	499	* @n: another type * to use as temporary storage
492	500	* @head: the head for your list.
493	501	* @member: the name of the list_struct within the struct.
	502	+ *
	503	+ * Iterate backwards over list of given type, safe against removal
	504	+ * of list entry.
494	505	*/
495	506	#define list_for_each_entry_safe_reverse(pos, n, head, member) \
496	507	for (pos = list_entry((head)->prev, typeof(*pos), member), \
497	508
...	...	@@ -518,12 +529,13 @@
518	529	pos = pos->next)
519	530
520	531	/**
521		- * list_for_each_safe_rcu - iterate over an rcu-protected list safe
522		- * against removal of list entry
	532	+ * list_for_each_safe_rcu
523	533	* @pos: the &struct list_head to use as a loop counter.
524	534	* @n: another &struct list_head to use as temporary storage
525	535	* @head: the head for your list.
526	536	*
	537	+ * Iterate over an rcu-protected list, safe against removal of list entry.
	538	+ *
527	539	* This list-traversal primitive may safely run concurrently with
528	540	* the _rcu list-mutation primitives such as list_add_rcu()
529	541	* as long as the traversal is guarded by rcu_read_lock().
530	542
...	...	@@ -551,11 +563,12 @@
551	563
552	564
553	565	/**
554		- * list_for_each_continue_rcu - iterate over an rcu-protected list
555		- * continuing after existing point.
	566	+ * list_for_each_continue_rcu
556	567	* @pos: the &struct list_head to use as a loop counter.
557	568	* @head: the head for your list.
558	569	*
	570	+ * Iterate over an rcu-protected list, continuing after current point.
	571	+ *
559	572	* This list-traversal primitive may safely run concurrently with
560	573	* the _rcu list-mutation primitives such as list_add_rcu()
561	574	* as long as the traversal is guarded by rcu_read_lock().
562	575
...	...	@@ -681,11 +694,14 @@
681	694
682	695
683	696	/**
684		- * hlist_add_head_rcu - adds the specified element to the specified hlist,
685		- * while permitting racing traversals.
	697	+ * hlist_add_head_rcu
686	698	* @n: the element to add to the hash list.
687	699	* @h: the list to add to.
688	700	*
	701	+ * Description:
	702	+ * Adds the specified element to the specified hlist,
	703	+ * while permitting racing traversals.
	704	+ *
689	705	* The caller must take whatever precautions are necessary
690	706	* (such as holding appropriate locks) to avoid racing
691	707	* with another list-mutation primitive, such as hlist_add_head_rcu()
692	708
...	...	@@ -730,11 +746,14 @@
730	746	}
731	747
732	748	/**
733		- * hlist_add_before_rcu - adds the specified element to the specified hlist
734		- * before the specified node while permitting racing traversals.
	749	+ * hlist_add_before_rcu
735	750	* @n: the new element to add to the hash list.
736	751	* @next: the existing element to add the new element before.
737	752	*
	753	+ * Description:
	754	+ * Adds the specified element to the specified hlist
	755	+ * before the specified node while permitting racing traversals.
	756	+ *
738	757	* The caller must take whatever precautions are necessary
739	758	* (such as holding appropriate locks) to avoid racing
740	759	* with another list-mutation primitive, such as hlist_add_head_rcu()
741	760
...	...	@@ -755,11 +774,14 @@
755	774	}
756	775
757	776	/**
758		- * hlist_add_after_rcu - adds the specified element to the specified hlist
759		- * after the specified node while permitting racing traversals.
	777	+ * hlist_add_after_rcu
760	778	* @prev: the existing element to add the new element after.
761	779	* @n: the new element to add to the hash list.
762	780	*
	781	+ * Description:
	782	+ * Adds the specified element to the specified hlist
	783	+ * after the specified node while permitting racing traversals.
	784	+ *
763	785	* The caller must take whatever precautions are necessary
764	786	* (such as holding appropriate locks) to avoid racing
765	787	* with another list-mutation primitive, such as hlist_add_head_rcu()
...	...	@@ -804,7 +826,7 @@
804	826	pos = pos->next)
805	827
806	828	/**
807		- * hlist_for_each_entry_continue - iterate over a hlist continuing after existing point
	829	+ * hlist_for_each_entry_continue - iterate over a hlist continuing after current point
808	830	* @tpos: the type * to use as a loop counter.
809	831	* @pos: the &struct hlist_node to use as a loop counter.
810	832	* @member: the name of the hlist_node within the struct.
...	...	@@ -816,7 +838,7 @@
816	838	pos = pos->next)
817	839
818	840	/**
819		- * hlist_for_each_entry_from - iterate over a hlist continuing from existing point
	841	+ * hlist_for_each_entry_from - iterate over a hlist continuing from current point
820	842	* @tpos: the type * to use as a loop counter.
821	843	* @pos: the &struct hlist_node to use as a loop counter.
822	844	* @member: the name of the hlist_node within the struct.