[PATCH wayland 1/2] util: Document wl_list methods

[Pekka Paalanen]

Hi Yong,

you may have missed the comment that this fundamental list design
comes from the kernel.


On Fri, 26 Aug 2016 11:12:59 +0200
Giulio Camuffo <giuliocamuffo at gmail.com> wrote:

> Hi,
> 
> 
> >
> > +/**
> > + * Removes an element from the list.
> > + *
> > + * \param elm element to remove from the list
> > + */  
> I think this should mention that elm is left in an invalid state, and
> the user should call wl_list_init on it before using it again.

No, not always.

wl_list_remove() does make the elm invalid.

However, wl_list_insert(list, elm) allows elm to be invalid, because it
will unconditionally overwrite it.

We use wl_list_insert() with uninitialized elm *a lot*.

> >  void
> >  wl_list_remove(struct wl_list *elm);
> >
> > +/**
> > + * Determines the length of the list.
> > + *
> > + * \note This is an O(n) operation.
> > + *
> > + * \param list list whose length is to be determined
> > + *
> > + * \return number of elements in the list
> > + */
> >  int
> >  wl_list_length(const struct wl_list *list);
> >
> > +/**
> > + * Determines if the list is empty.
> > + *
> > + * \param list list whose emptiness is to be determined
> > + *
> > + * \return 1 if empty, or 0 if not empty
> > + */
> >  int
> >  wl_list_empty(const struct wl_list *list);
> >
> > +/**
> > + * Inserts all of the elements of one list into another, after the element
> > + * represented by `list`.
> > + *
> > + * \param list list element after which the other list elements will be inserted
> > + * \param other list of elements to insert

This leaves 'other' as invalid.

> > + *
> > + */
> >  void
> >  wl_list_insert_list(struct wl_list *list, struct wl_list *other);
> >


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20160831/6a0c7a70/attachment.sig>