Date:   Thu, 02 Jul 2020 10:33:16 +0000
From:   OrToledano <ortoledano@...tonmail.com>
To:     "paulmck@...nel.org" <paulmck@...nel.org>,
        "axboe@...nel.dk" <axboe@...nel.dk>,
        "jkosina@...e.cz" <jkosina@...e.cz>,
        "asml.silence@...il.com" <asml.silence@...il.com>,
        "neilb@...e.com" <neilb@...e.com>,
        "edumazet@...gle.com" <edumazet@...gle.com>,
        "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>
Subject: [PATCH] list: documentation changes


There are & in the documentation for struct pointers, but not for head.
&head in the documentation would be beneficial, since we initialize the
head with LIST_HEAD(name) which creates struct list_head name;
That means in order to pass name to the macros, we need to use &name, and
good documentation can indicate that.

Additionally, I changed "for your list" to "of the list" for consistency
("of the list" occurs more often, and is used exclusively in hashtable.h).

Signed-off-by: Or Toledano <ortoledano@...tonmail.com>
---
 include/linux/list.h | 54 ++++++++++++++++++++++----------------------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/include/linux/list.h b/include/linux/list.h
index aff44d34f4e4..5bd7c61d9024 100644
--- a/include/linux/list.h
+++ b/include/linux/list.h
@@ -76,7 +76,7 @@ static inline void __list_add(struct list_head *new,
 /**
  * list_add - add a new entry
  * @new: new entry to be added
- * @head: list head to add it after
+ * @head: the &head to add it after
  *
  * Insert a new entry after the specified head.
  * This is good for implementing stacks.
@@ -90,7 +90,7 @@ static inline void list_add(struct list_head *new, struct list_head *head)
 /**
  * list_add_tail - add a new entry
  * @new: new entry to be added
- * @head: list head to add it before
+ * @head: the &head to add it before
  *
  * Insert a new entry before the specified head.
  * This is useful for implementing queues.
@@ -208,7 +208,7 @@ static inline void list_del_init(struct list_head *entry)
 /**
  * list_move - delete from one list and add as another's head
  * @list: the entry to move
- * @head: the head that will precede our entry
+ * @head: the &head that will precede our entry
  */
 static inline void list_move(struct list_head *list, struct list_head *head)
 {
@@ -219,7 +219,7 @@ static inline void list_move(struct list_head *list, struct list_head *head)
 /**
  * list_move_tail - delete from one list and add as another's tail
  * @list: the entry to move
- * @head: the head that will follow our entry
+ * @head: the &head that will follow our entry
  */
 static inline void list_move_tail(struct list_head *list,
 				  struct list_head *head)
@@ -230,7 +230,7 @@ static inline void list_move_tail(struct list_head *list,

 /**
  * list_bulk_move_tail - move a subsection of a list to its tail
- * @head: the head that will follow our entry
+ * @head: the &head that will follow our entry
  * @first: first entry to move
  * @last: last entry to move, can be the same as first
  *
@@ -254,7 +254,7 @@ static inline void list_bulk_move_tail(struct list_head *head,
 /**
  * list_is_first -- tests whether @list is the first entry in list @head
  * @list: the entry to test
- * @head: the head of the list
+ * @head: the &head of the list
  */
 static inline int list_is_first(const struct list_head *list,
 					const struct list_head *head)
@@ -265,7 +265,7 @@ static inline int list_is_first(const struct list_head *list,
 /**
  * list_is_last - tests whether @list is the last entry in list @head
  * @list: the entry to test
- * @head: the head of the list
+ * @head: the &head of the list
  */
 static inline int list_is_last(const struct list_head *list,
 				const struct list_head *head)
@@ -303,7 +303,7 @@ static inline int list_empty_careful(const struct list_head *head)

 /**
  * list_rotate_left - rotate the list to the left
- * @head: the head of the list
+ * @head: the &head of the list
  */
 static inline void list_rotate_left(struct list_head *head)
 {
@@ -318,7 +318,7 @@ static inline void list_rotate_left(struct list_head *head)
 /**
  * list_rotate_to_front() - Rotate list to specific item.
  * @list: The desired new front of the list.
- * @head: The head of the list.
+ * @head: The &head of the list.
  *
  * Rotates list so that @list becomes the new front of the list.
  */
@@ -547,7 +547,7 @@ static inline void list_splice_tail_init(struct list_head *list,
 /**
  * list_for_each	-	iterate over a list
  * @pos:	the &struct list_head to use as a loop cursor.
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  */
 #define list_for_each(pos, head) \
 	for (pos = (head)->next; pos != (head); pos = pos->next)
@@ -555,7 +555,7 @@ static inline void list_splice_tail_init(struct list_head *list,
 /**
  * list_for_each_continue - continue iteration over a list
  * @pos:	the &struct list_head to use as a loop cursor.
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  *
  * Continue to iterate over a list, continuing after the current position.
  */
@@ -565,7 +565,7 @@ static inline void list_splice_tail_init(struct list_head *list,
 /**
  * list_for_each_prev	-	iterate over a list backwards
  * @pos:	the &struct list_head to use as a loop cursor.
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  */
 #define list_for_each_prev(pos, head) \
 	for (pos = (head)->prev; pos != (head); pos = pos->prev)
@@ -574,7 +574,7 @@ static inline void list_splice_tail_init(struct list_head *list,
  * list_for_each_safe - iterate over a list safe against removal of list entry
  * @pos:	the &struct list_head to use as a loop cursor.
  * @n:		another &struct list_head to use as temporary storage
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  */
 #define list_for_each_safe(pos, n, head) \
 	for (pos = (head)->next, n = pos->next; pos != (head); \
@@ -584,7 +584,7 @@ static inline void list_splice_tail_init(struct list_head *list,
  * list_for_each_prev_safe - iterate over a list backwards safe against removal of list entry
  * @pos:	the &struct list_head to use as a loop cursor.
  * @n:		another &struct list_head to use as temporary storage
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  */
 #define list_for_each_prev_safe(pos, n, head) \
 	for (pos = (head)->prev, n = pos->prev; \
@@ -594,7 +594,7 @@ static inline void list_splice_tail_init(struct list_head *list,
 /**
  * list_for_each_entry	-	iterate over list of given type
  * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the list_head within the struct.
  */
 #define list_for_each_entry(pos, head, member)				\
@@ -605,7 +605,7 @@ static inline void list_splice_tail_init(struct list_head *list,
 /**
  * list_for_each_entry_reverse - iterate backwards over list of given type.
  * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the list_head within the struct.
  */
 #define list_for_each_entry_reverse(pos, head, member)			\
@@ -616,7 +616,7 @@ static inline void list_splice_tail_init(struct list_head *list,
 /**
  * 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
+ * @head:	the &head of the list
  * @member:	the name of the list_head within the struct.
  *
  * Prepares a pos entry for use as a start point in list_for_each_entry_continue().
@@ -627,7 +627,7 @@ static inline void list_splice_tail_init(struct list_head *list,
 /**
  * list_for_each_entry_continue - continue iteration over list of given type
  * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the list_head within the struct.
  *
  * Continue to iterate over list of given type, continuing after
@@ -641,7 +641,7 @@ static inline void list_splice_tail_init(struct list_head *list,
 /**
  * list_for_each_entry_continue_reverse - iterate backwards from the given point
  * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the list_head within the struct.
  *
  * Start to iterate over list of given type backwards, continuing after
@@ -655,7 +655,7 @@ static inline void list_splice_tail_init(struct list_head *list,
 /**
  * list_for_each_entry_from - iterate over list of given type from the current point
  * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the list_head within the struct.
  *
  * Iterate over list of given type, continuing from current position.
@@ -668,7 +668,7 @@ static inline void list_splice_tail_init(struct list_head *list,
  * list_for_each_entry_from_reverse - iterate backwards over list of given type
  *                                    from the current point
  * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the list_head within the struct.
  *
  * Iterate backwards over list of given type, continuing from current position.
@@ -681,7 +681,7 @@ static inline void list_splice_tail_init(struct list_head *list,
  * list_for_each_entry_safe - iterate over list of given type safe against removal of list entry
  * @pos:	the type * to use as a loop cursor.
  * @n:		another type * to use as temporary storage
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the list_head within the struct.
  */
 #define list_for_each_entry_safe(pos, n, head, member)			\
@@ -694,7 +694,7 @@ static inline void list_splice_tail_init(struct list_head *list,
  * list_for_each_entry_safe_continue - continue list iteration safe against removal
  * @pos:	the type * to use as a loop cursor.
  * @n:		another type * to use as temporary storage
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the list_head within the struct.
  *
  * Iterate over list of given type, continuing after current point,
@@ -710,7 +710,7 @@ static inline void list_splice_tail_init(struct list_head *list,
  * list_for_each_entry_safe_from - iterate over list from current point safe against removal
  * @pos:	the type * to use as a loop cursor.
  * @n:		another type * to use as temporary storage
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the list_head within the struct.
  *
  * Iterate over list of given type from current point, safe against
@@ -725,7 +725,7 @@ static inline void list_splice_tail_init(struct list_head *list,
  * list_for_each_entry_safe_reverse - iterate backwards over list safe against removal
  * @pos:	the type * to use as a loop cursor.
  * @n:		another type * to use as temporary storage
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the list_head within the struct.
  *
  * Iterate backwards over list of given type, safe against removal
@@ -959,7 +959,7 @@ static inline void hlist_move_list(struct hlist_head *old,
 /**
  * hlist_for_each_entry	- iterate over list of given type
  * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the hlist_node within the struct.
  */
 #define hlist_for_each_entry(pos, head, member)				\
@@ -990,7 +990,7 @@ static inline void hlist_move_list(struct hlist_head *old,
  * hlist_for_each_entry_safe - iterate over list of given type safe against removal of list entry
  * @pos:	the type * to use as a loop cursor.
  * @n:		a &struct hlist_node to use as temporary storage
- * @head:	the head for your list.
+ * @head:	the &head of the list.
  * @member:	the name of the hlist_node within the struct.
  */
 #define hlist_for_each_entry_safe(pos, n, head, member) 		\
--
2.26.2

Powered by blists - more mailing lists