lib: revise list_sort() header comment

Clarify and correct header comment of list_sort(). Signed-off-by: Don Mullis <don.mullis@gmail.com> Cc: Dave Airlie <airlied@redhat.com> Cc: Andi Kleen <andi@firstfloor.org> Cc: Dave Chinner <david@fromorbit.com> Cc: Artem Bityutskiy <dedekind@infradead.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

lib: revise list_sort() header comment
Clarify and correct header comment of list_sort(). Signed-off-by: Don Mullis <don.mullis@gmail.com> Cc: Dave Airlie <airlied@redhat.com> Cc: Andi Kleen <andi@firstfloor.org> Cc: Dave Chinner <david@fromorbit.com> Cc: Artem Bityutskiy <dedekind@infradead.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Don Mullis · Linus Torvalds
1 parent 835cc0c847
Showing 1 changed file with 8 additions and 7 deletions Side-by-side Diff
lib/list_sort.c
@@ -81,17 +81,18 @@
 }
  
 /**
- * list_sort - sort a list.
- * @priv: private data, passed to @cmp
+ * list_sort - sort a list
+ * @priv: private data, opaque to list_sort(), passed to @cmp
  * @head: the list to sort
  * @cmp: the elements comparison function
  *
- * This function implements "merge sort" which has O(nlog(n)) complexity.
- * The list is sorted in ascending order.
+ * This function implements "merge sort", which has O(nlog(n))
+ * complexity.
  *
- * The comparison function @cmp is supposed to return a negative value if @a is
- * less than @b, and a positive value if @a is greater than @b. If @a and @b
- * are equivalent, then it does not matter what this function returns.
+ * The comparison function @cmp must return a negative value if @a
+ * should sort before @b, and a positive value if @a should sort after
+ * @b. If @a and @b are equivalent, and their original relative
+ * ordering is to be preserved, @cmp must return 0.
  */
 void list_sort(void *priv, struct list_head *head,
 		int (*cmp)(void *priv, struct list_head *a,
...	...	@@ -81,17 +81,18 @@
81	81	}
82	82
83	83	/**
84		- * list_sort - sort a list.
85		- * @priv: private data, passed to @cmp
	84	+ * list_sort - sort a list
	85	+ * @priv: private data, opaque to list_sort(), passed to @cmp
86	86	* @head: the list to sort
87	87	* @cmp: the elements comparison function
88	88	*
89		- * This function implements "merge sort" which has O(nlog(n)) complexity.
90		- * The list is sorted in ascending order.
	89	+ * This function implements "merge sort", which has O(nlog(n))
	90	+ * complexity.
91	91	*
92		- * The comparison function @cmp is supposed to return a negative value if @a is
93		- * less than @b, and a positive value if @a is greater than @b. If @a and @b
94		- * are equivalent, then it does not matter what this function returns.
	92	+ * The comparison function @cmp must return a negative value if @a
	93	+ * should sort before @b, and a positive value if @a should sort after
	94	+ * @b. If @a and @b are equivalent, and their original relative
	95	+ * ordering is to be preserved, @cmp must return 0.
95	96	*/
96	97	void list_sort(void priv, struct list_head head,
97	98	int (cmp)(void priv, struct list_head *a,