Re: [PATCH 2/4] list.h: add list_cut_position()

[Randy Dunlap <randy.dunlap@oracle.com>]

> This adds list_cut_position() which lets you cut a list into
> two lists given a pivot in the list.
> 
> Signed-off-by: Luis R. Rodriguez <lrodriguez@atheros.com>
> 
> diff --git a/include/linux/list.h b/include/linux/list.h
> index 453916b..6c02a83 100644
> --- a/include/linux/list.h
> +++ b/include/linux/list.h
> @@ -214,6 +214,46 @@ static inline int list_is_singular(const
> struct list_head *head)
>  	return !list_empty(head) && (head->next == head->prev);
>  }
>  
> +static inline void __list_cut_position(struct list_head *list,
> +		struct list_head *head, struct list_head *entry)
> +{
> +	struct list_head *new_first = entry->next;
> +	list->next = head->next;
> +	list->next->prev = list;
> +	list->prev = entry;
> +	entry->next = list;
> +	head->next = new_first;
> +	new_first->prev = head;
> +}
> +
> +/**
> + * list_cut_position - cut a list into two
> + *
> + * This helper moves the initial part of @head, up to and
> + * including @entry, from @head to @list. You should
> + * pass on @entry an element you know is on @head. @list
> + * should be an empty list or a list you do not care about
> + * losing its data.
> + *
> + * @list: a new list to add all removed entries
> + * @head: a list with entries
> + * @entry: an entry within head, could be the head itself
> + *	and if so we won't cut the list
> + */

For kernel-doc notation, the parameters need to follow the function name+short description.
After that, a longer description can be added.  I.e., please move the parameters up to
above the longer description...

> +static inline void list_cut_position(struct list_head *list,
> +		struct list_head *head, struct list_head *entry)
> +{
> +	if (list_empty(head))
> +		return;
> +	if (list_is_singular(head) &&
> +		(head->next != entry && head != entry))
> +		return;
> +	if (entry == head)
> +		INIT_LIST_HEAD(list);
> +	else
> +		__list_cut_position(list, head, entry);
> +}
> +
>  static inline void __list_splice(const struct list_head *list,
>  				 struct list_head *head)
>  {