[PATCH 6/6] utils: Document wl_list methods

[Aaron Faanes]

On Tue, Sep 17, 2013 at 12:15 AM, Kristian Høgsberg <hoegsberg at gmail.com>wrote:

> On Sun, Sep 15, 2013 at 01:37:11PM -0500, Aaron Faanes wrote:
> > +/** Inserts the specified element directly after the specified list
> node.
> > + *
> > + * \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);
>
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.
>

 /** Inserts the specified element into the specified list.
 *
 * If \c list is a list head, then \c elm will be prepended to that list.
 * Otherwise, if \c list is another node, then \c elm will be inserted
directly
 * after it (or appended if \c list is the last list node).
 *
 * \param list Either a list node or a list head
 * \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);

I tried to be more specific in how list heads vs. list nodes are handled. I
may have misunderstood you here, so lemme know if you wanted to specify
that only prepending and appending are supported, as I'm assuming that
insertion at any node is allowed (at least ones that are in lists).

 > +/** 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.
>

/** Inserts all elements in the specified other list into \c
list.
 *

 * All elements in \c other will be added in order directly before \c
list.
 *

 *
~~~

 * wl_list list; \comment{[1, 2,
3]}

 * wl_list other; \comment{[4, 5,
6]}

 *

 * wl_list_insert_list(&list,
&other);

 * \comment{list now contains [4, 5, 6, 1, 2,
3]}
 * \comment{other is now undefined; be sure to call wl_list_init before
reuse}
 *
~~~

 *

 * \param list The list that will be added
to
 * \param other The list that contains the elements to add. This list
will
 * become undefined after this call; it must be re-initialized
with
 * wl_list_init before it can be used
again.

 *

 * \memberof
wl_list

 */

void wl_list_insert_list(struct wl_list *list, struct wl_list *other);

I updated the comment and the \param to point out the re-iniialization
requirement. I also cleaned up the style a bit (e.g. use \comment instead
of //, don't use foo/bar)

Upon thinking on it, I wonder if it would be more prudent to have
wl_list_insert_list call wl_list_init on the other list instead of leaving
it undefined?

-- 
Aaron Faanes <dafrito at gmail.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20130917/afdaa414/attachment.html>