[gtk+] GtkTreeModel: add more detailed documentation on reference counting

[Kristian Rietveld <kristian src gnome org>]

commit 85d4a5abc7c7b1a87b9eb118d1216ead0c00b3ec
Author: Kristian Rietveld <kris gtk org>
Date:   Thu Aug 11 10:42:29 2011 +0200

    GtkTreeModel: add more detailed documentation on reference counting

 gtk/gtktreemodel.c |   41 ++++++++++++++++++++++++++++++++++++++---
 1 files changed, 38 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index 26f6d73..02ea9c9 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -197,6 +197,36 @@
  * </programlisting>
  * </example>
  *
+ * The #GtkTreeModel interface contains two methods for reference
+ * counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node().
+ * These two methods are optional to implement. The reference counting
+ * is meant as a way for views to let models know when nodes are being
+ * displayed. #GtkTreeView will take a reference on a node when it is
+ * visible, which means the node is either in the toplevel or expanded.
+ * Being displayed does not mean that the node is currently directly
+ * visible to the user in the viewport. Based on this reference counting
+ * scheme a caching model, for example, can decide whether or not to cache
+ * a node based on the reference count. A file-system based model would
+ * not want to keep the entire file hierarchy in memory, but just the
+ * folders that are currently expanded in every current view.
+ *
+ * When working with reference counting, the following rules must be taken
+ * into account:
+ * <itemizedlist>
+ * <listitem><para>Never take a reference on a node without owning a
+ * reference on its parent. This means that all parent nodes of a referenced
+ * node must be referenced as well.</para></listitem>
+ * <listitem><para>Outstanding references on a deleted node are not released.
+ * This is not possible because the node has already been deleted by the
+ * time the row-deleted signal is received.
+ * </para></listitem>
+ * <listitem><para>Models are not obligated to emit a signal on rows of
+ * which none of its siblings are referenced. To phrase this differently,
+ * signals are only required for levels in which nodes are referenced. For
+ * the root level however, signals must be emitted at all times (however the
+ * root level is always referenced when any view is attached).
+ * </para></listitem>
+ * </itemizedlist>
  */
 
 #define INITIALIZE_TREE_ITER(Iter) \
@@ -1615,9 +1645,11 @@ gtk_tree_model_iter_parent (GtkTreeModel *tree_model,
  *
  * This function is primarily meant as a way for views to let
  * caching models know when nodes are being displayed (and hence,
- * whether or not to cache that node). For example, a file-system
- * based model would not want to keep the entire file-hierarchy in
- * memory, just the sections that are currently being displayed by
+ * whether or not to cache that node). Being displayed means a node
+ * is in an expanded branch, regardless of whether the node is currently
+ * visible in the viewport. For example, a file-system based model
+ * would not want to keep the entire file-hierarchy in memory,
+ * just the sections that are currently being displayed by
  * every current view.
  *
  * A model should be expected to be able to get an iter independent
@@ -1824,6 +1856,9 @@ gtk_tree_model_row_has_child_toggled (GtkTreeModel *tree_model,
  * This should be called by models after a row has been removed.
  * The location pointed to by @path should be the location that
  * the row previously was at. It may not be a valid location anymore.
+ *
+ * Nodes that are deleted are not unreffed, this means that any
+ * outstanding references on the deleted node should not be released.
  */
 void
 gtk_tree_model_row_deleted (GtkTreeModel *tree_model,