From: Benjamin Otte <otte@redhat.com>
Date: Sun, 19 Mar 2023 04:25:52 +0000 (+0100)
Subject: treelistmodel: Clarify docs
X-Git-Tag: archive/raspbian/4.12.3+ds-1+rpi1~1^2^2^2~22^2~1^2~527^2
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=c4636852;p=gtk4.git

treelistmodel: Clarify docs

No user knows that we have an internal function called
gtk_tree_list_row_destroy() that gets called when a row gets removed
from the treelistmodel.

So everyone was probably just making stuff up about what "destroy"
means.

Related: #5646
---

diff --git a/gtk/gtktreelistmodel.c b/gtk/gtktreelistmodel.c
index fe9240e4b4..8a189fe2ce 100644
--- a/gtk/gtktreelistmodel.c
+++ b/gtk/gtktreelistmodel.c
@@ -1120,7 +1120,8 @@ gtk_tree_list_row_get_position (GtkTreeListRow *self)
  * of zero, rows corresponding to items of models of direct children
  * of the root model have a depth of 1 and so on.
  *
- * The depth of a row never changes until the row is destroyed.
+ * The depth of a row never changes until the row is removed from its model
+ * at which point it will forever return 0.
  *
  * Returns: The depth of this row
  */
@@ -1228,7 +1229,8 @@ gtk_tree_list_row_get_expanded (GtkTreeListRow *self)
  * This does not mean that the row is actually expanded,
  * this can be checked with [method@Gtk.TreeListRow.get_expanded].
  *
- * If a row is expandable never changes until the row is destroyed.
+ * If a row is expandable never changes until the row is removed
+ * from its model at which point it will forever return %FALSE.
  *
  * Returns: %TRUE if the row is expandable
  */
@@ -1315,7 +1317,8 @@ gtk_tree_list_row_get_children (GtkTreeListRow *self)
  * %NULL is returned.
  *
  * The value returned by this function never changes
- * until the row is destroyed.
+ * until the row is removed from its model at which point
+ * it will forever return %NULL.
  *
  * Returns: (nullable) (transfer full): The parent of @self
  */