[PATCH 6/6] utils: Document wl_list methods

[Kristian Høgsberg]

On Sun, Sep 15, 2013 at 01:37:11PM -0500, Aaron Faanes wrote:
> ---
> 
> As I understand it, a wl_list can be either content-bearing node or a list head.
> I believe this is correct, but if it isn't (in other words, there is no distinction
> between list heads and content-bearing elements), then this documentation is going
> to be tragically incorrect.

No, you're right.  A list has a dummy struct wl_list as the head
element (typically embedded in the struct that owns the list) and the
rest of the elements carray actual data (embedded in the structs that
are the elements of the list).

>  src/wayland-util.h | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 64 insertions(+)
> 
> diff --git a/src/wayland-util.h b/src/wayland-util.h
> index 51de3f6..86d03f2 100644
> --- a/src/wayland-util.h
> +++ b/src/wayland-util.h
> @@ -115,11 +115,75 @@ struct wl_list {
>  	struct wl_list *next;
>  };
>  
> +/** Initializes a new wl_list for use as a list.

Let's be more precise and say "as a list head" here.

> + *
> + * There is no need to call this method for wl_list nodes that will only be used as
> + * elements within other lists, though there is no harm in doing so.
> + *
> + * \param list The list that will be initialized.
> + *
> + * \memberof wl_list
> + */
>  void wl_list_init(struct wl_list *list);
> +
> +/** Inserts the specified element directly after the specified list node.

Maybe we can add something like: The list node can be either the list
head, in which case the element is prepended to the list, or the last
list node, in which case the element will be appended to the list.

> + *
> + * \param list the list that will be directly previous to \c elm
> + * \param elm The element that will be added after \c list
> + *
> + * \memberof wl_list
> + */
>  void wl_list_insert(struct wl_list *list, struct wl_list *elm);
> +
> +/** Removes the specified wl_list node from the list that contains it.
> + *
> + * \param elm the list to remove
> + *
> + * \memberof wl_list
> + */
>  void wl_list_remove(struct wl_list *elm);
> +
> +/** Returns the number of elements in the specified list.
> + *
> + * Prefer #wl_list_empty if you're just interested if the list is empty.
> + *
> + * \param list The list that will be queried.
> + * \return The number of elements in the specified list.
> + *
> + * \sa wl_list_empty
> + * \memberof wl_list
> + */
>  int wl_list_length(const struct wl_list *list);
> +
> +/** Queries whether the specified list is empty.
> + *
> + * This method runs in O(1).
> + *
> + * \param list The list that will be queried.
> + * \return \c true if the list is empty, \c false otherwise
> + *
> + * \sa wl_list_length
> + * \memberof wl_list
> + */
>  int wl_list_empty(const struct wl_list *list);
> +
> +/** Inserts all elements in the specified other list into \c list.
> + *
> + * All elements in \other will be added in order directly before \c list.
> + *
> + * \code
> + * wl_list foo; // [1, 2, 3]
> + * wl_list bar; // [4, 5, 6]
> + *
> + * wl_list_insert_list(&foo, &other);
> + * // foo now contains [4, 5, 6, 1, 2, 3]
> + * \endcode

I'd spell out that bar is now undefined and needs to be re-initialized
with wl_list_init() if we're going to add elements to it again.

Kristian

> + * \param list The list that will be added to
> + * \param other The list that contains the elements to add.
> + *
> + * \memberof wl_list
> + */
>  void wl_list_insert_list(struct wl_list *list, struct wl_list *other);
>  
>  /**
> -- 
> 1.8.3.1
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel