Clarify that one cannot use the same variable

A naive way to perform an action on all parent nodes of a given node
could be to do:

while(gtk_tree_model_iter_parent(model, &iter, &iter)) {
	/* perform some action on iter here */
}

However, since gtk_tree_model_iter_parent() will initialize the iterator
pointed to by the second parameter before performing the lookup, this
will not work.

Explicitly document this behaviour.

Signed-off-by: Wouter Verhelst <w@uter.be>
https://bugzilla.gnome.org/show_bug.cgi?id=573380

diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index 5e447b9a2e24a482ad0a73a48b4ad570ec73536e..500658b5c1aff263613637173175f8f1e7b3d869 100644 (file)
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -1640,6 +1640,9 @@ gtk_tree_model_iter_nth_child (GtkTreeModel *tree_model,
  * @child will remain a valid node after this function has been
  * called.
  *
+ * @iter will be initialized before the lookup is performed, so @child
+ * and @iter cannot point to the same memory location.
+ *
  * Returns: %TRUE, if @iter is set to the parent of @child
  */
 gboolean