[PATCH] include: document list interface.

[Peter Hutterer]

On Tue, Feb 22, 2011 at 12:56:41PM -0800, Alan Coopersmith wrote:
> > + * Looping through the list requires a 'struct foo' as iterator and the
> > + * name of the field the subnodes use.
> 
> Looks like this should this say:
> 	a 'struct foo' as iterator, the head of the list, and the
> 	name of the field the subnodes use.
> to parallel the three arguments shown:

technically yes, but that's not always the case. AFAICT think this loop
works on any node, though in this example the list head is used.

> > + * struct foo *iterator;
> > + * list_for_each_entry(iterator, &bar.foos, entry) {
> > + *      if (iterator->something == ...)
> > + *             ...
> > + * }
> > + *
> > + * Note: You must not call list_del() on the iterator if you continue the
> > + * loop. You need to run the safe for-each loop instead:
> > + *
> > + * struct foo *iterator, *next;
> > + * list_for_each_entry(iterator, next, &bar.foos, entry) {
> > + *      if (...)
> > + *              list_del(&iterator->entry);
> > + * }
> 
> 
> Shouldn't that be list_for_each_entry_safe ?

oops
 
> > @@ -61,6 +166,20 @@ __list_del(struct list *prev, struct list *next)
> >      prev->next = next;
> >  }
> >  
> > +/**
> > + * Remove the element from the list it is in. Using this function will reset
> > + * the pointers to-fro this element so it is removed from the list. It does
> 
> fro -> from ?

awwww, you're destroying my efforts in being all class :)
http://dictionary.reference.com/browse/fro

patch coming in a tick
 
Cheers,
  Peter