gst/gstiterator.*: After 3 years it's about time to revise the documentation of the iterator objects.

Original commit message from CVS:
* gst/gstiterator.c:
* gst/gstiterator.h:
After 3 years it's about time to revise the documentation of the
iterator objects.

ChangeLog

@@ -1,3 +1,10 @@
+2008-08-29  Wim Taymans  <wim.taymans@collabora.co.uk>
+
+	* gst/gstiterator.c:
+	* gst/gstiterator.h:
+	After 3 years it's about time to revise the documentation of the
+	iterator objects.
+
 2008-08-29  Wim Taymans  <wim.taymans@collabora.co.uk>
 
 	* gst/gstpad.c: (gst_pad_get_internal_links_default):

gst/gstiterator.c

@@ -61,7 +61,7 @@
  *   </programlisting>
  * </example>
  *
- * Last reviewed on 2005-11-09 (0.9.4)
+ * Last reviewed on 2008-08-29 (0.10.21)
  */
 
 #include "gst_private.h"
@@ -92,7 +92,8 @@ gst_iterator_init (GstIterator * it,
  * @size: the size of the iterator structure
  * @type: #GType of children
  * @lock: pointer to a #GMutex.
- * @master_cookie: pointer to a guint32 to protect the iterated object.
+ * @master_cookie: pointer to a guint32 that is changed when the items in the
+ *    iterator changed.
  * @next: function to get next item
  * @item: function to call on each item retrieved
  * @resync: function to resync the iterator
@@ -176,7 +177,8 @@ gst_list_iterator_free (GstListIterator * it)
  * gst_iterator_new_list:
  * @type: #GType of elements
  * @lock: pointer to a #GMutex protecting the list.
- * @master_cookie: pointer to a guint32 to protect the list.
+ * @master_cookie: pointer to a guint32 that is incremented when the list
+ *     is changed.
  * @list: pointer to the list
  * @owner: object owning the list
  * @item: function to call for each item
@@ -184,6 +186,24 @@ gst_list_iterator_free (GstListIterator * it)
  *
  * Create a new iterator designed for iterating @list.
  *
+ * The list you iterate is usually part of a data structure @owner and is
+ * protected with @lock. 
+ *
+ * The iterator will use @lock to retrieve the next item of the list and it
+ * will then call the @item function before releasing @lock again.
+ *
+ * The @item function usualy makes sure that the item remains alive while
+ * @lock is released and the application is using the item. The application is
+ * responsible for freeing/unreffing the item after usage as explained in
+ * gst_iterator_next().
+ *
+ * When a concurrent update to the list is performed, usually by @owner while
+ * holding @lock, @master_cookie will be updated. The iterator implementation
+ * will notice the update of the cookie and will return #GST_ITERATOR_RESYNC to
+ * the user of the iterator in the next call to gst_iterator_next().
+ *
+ * @owner will be passed to the @free function when the iterator is freed.
+ *
  * Returns: the new #GstIterator for @list.
  *
  * MT safe.
@@ -230,12 +250,24 @@ gst_iterator_pop (GstIterator * it)
  * @it: The #GstIterator to iterate
  * @elem: pointer to hold next element
  *
- * Get the next item from the iterator. For iterators that return
- * refcounted objects, the returned object will have its refcount
- * increased and should therefore be unreffed after usage.
+ * Get the next item from the iterator in @elem. 
  *
- * Returns: The result of the iteration. Unref after usage if this is
- * a refcounted object.
+ * Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
+ * value. For iterators that return refcounted objects, the returned object
+ * will have its refcount increased and should therefore be unreffed after
+ * usage.
+ *
+ * When this function returns %GST_ITERATOR_DONE, no more elements can be
+ * retrieved from @it.
+ *
+ * A return value of %GST_ITERATOR_RESYNC indicates that the element list was
+ * concurrently updated. The user of @it should call gst_iterator_resync() to
+ * get the newly updated list. 
+ *
+ * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
+ *
+ * Returns: The result of the iteration. Unref @elem after usage if this
+ * is a refcounted object.
  *
  * MT safe.
  */
@@ -299,6 +331,9 @@ done:
  * Resync the iterator. this function is mostly called
  * after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
  *
+ * When an iterator was pushed on @it, it will automatically be popped again
+ * with this function.
+ *
  * MT safe.
  */
 void
@@ -340,12 +375,15 @@ gst_iterator_free (GstIterator * it)
  * @other: The #GstIterator to push
  *
  * Pushes @other iterator onto @it. All calls performed on @it are
- * forwarded tot @other. If @other returns #GST_ITERATOR_DONE, it is
+ * forwarded to @other. If @other returns #GST_ITERATOR_DONE, it is
  * popped again and calls are handled by @it again.
  *
  * This function is mainly used by objects implementing the iterator
  * next function to recurse into substructures.
  *
+ * When gst_iterator_resync() is called on @it, @other will automatically be
+ * popped.
+ *
  * MT safe.
  */
 void
@@ -467,8 +505,8 @@ gst_iterator_filter (GstIterator * it, GCompareFunc func, gpointer user_data)
  * @ret: the seed value passed to the fold function
  * @user_data: user data passed to the fold function
  *
- * Folds @func over the elements of @iter. That is to say, @proc will be called
- * as @proc (object, @ret, @user_data) for each object in @iter. The normal use
+ * Folds @func over the elements of @iter. That is to say, @func will be called
+ * as @func (object, @ret, @user_data) for each object in @it. The normal use
  * of this procedure is to accumulate the results of operating on the objects in
  * @ret.
  *

gst/gstiterator.h

@@ -51,7 +51,7 @@ typedef struct _GstIterator GstIterator;
  * @GST_ITERATOR_ITEM_PASS:  Return item
  * @GST_ITERATOR_ITEM_END:   Stop after this item.
  *
- * The result of a GstIteratorItemFunction.
+ * The result of a #GstIteratorItemFunction.
  */
 typedef enum {
   GST_ITERATOR_ITEM_SKIP	= 0,
@@ -63,8 +63,8 @@ typedef enum {
  * GstIteratorDisposeFunction:
  * @owner: the owner of the iterator
  *
- * The function that will be called when a GList iterator is freed. The
- * owner of the GList iterator can then clean up its resources.
+ * The function that will be called when a #GList iterator is freed. The
+ * owner of the #GList iterator can then clean up its resources.
  */
 typedef void		  (*GstIteratorDisposeFunction)	(gpointer owner);
 
@@ -128,7 +128,7 @@ typedef void		  (*GstIteratorFreeFunction)	(GstIterator *it);
 /**
  * GstIteratorFoldFunction:
  * @item: the item to fold
- * @ret: a GValue collecting the result
+ * @ret: a #GValue collecting the result
  * @user_data: data passed to gst_iterator_fold()
  *
  * A function to be passed to gst_iterator_fold().
@@ -186,7 +186,7 @@ typedef gboolean	  (*GstIteratorFoldFunction)    (gpointer item, GValue *ret, gp
  *          created.
  * @master_cookie: A pointer to the master cookie.
  *
- * GstIterator base structure. The values of this structure are 
+ * #GstIterator base structure. The values of this structure are 
  * protected for subclasses, use the methods to use the #GstIterator.
  */
 struct _GstIterator {