[gtk/wip/otte/listview: 1/157] treelistmodel: Improve docs

[Benjamin Otte <otte src gnome org>]

commit 8de9e42ce5294375cb058ae54eeaf6d9287b924c
Author: Benjamin Otte <otte redhat com>
Date:   Fri Dec 13 07:45:57 2019 +0100

    treelistmodel: Improve docs
    
    - Move into its own section
    - Split GtkTreeListRow into its own document
    
    Trees are weird with listmodels and they deserve their own treatment,
    they shouldn't be mushed up with the rest of the list machinery.

 docs/reference/gtk/gtk4-docs.xml     |  6 +++++-
 docs/reference/gtk/gtk4-sections.txt | 42 ++++++++++++++++++++----------------
 docs/reference/gtk/gtk4.types.in     |  1 +
 gtk/gtktreelistmodel.c               | 19 +++++++++++++++-
 4 files changed, 47 insertions(+), 21 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml
index 68940e40b0..8d65aecd3d 100644
--- a/docs/reference/gtk/gtk4-docs.xml
+++ b/docs/reference/gtk/gtk4-docs.xml
@@ -49,12 +49,16 @@
       <xi:include href="xml/gtkmaplistmodel.xml" />
       <xi:include href="xml/gtkslicelistmodel.xml" />
       <xi:include href="xml/gtksortlistmodel.xml" />
-      <xi:include href="xml/gtktreelistmodel.xml" />
       <xi:include href="xml/gtkselectionmodel.xml" />
       <xi:include href="xml/gtknoselection.xml" />
       <xi:include href="xml/gtksingleselection.xml" />
     </chapter>
 
+    <chapter id="Trees">
+      <xi:include href="xml/gtktreelistrow.xml" />
+      <xi:include href="xml/gtktreelistmodel.xml" />
+    </chapter>
+
     <chapter id="Application">
       <title>Application support</title>
       <xi:include href="xml/gtkapplication.xml" />
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 96de634b5d..1698de99b0 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -3451,6 +3451,29 @@ GTK_TOOLTIP
 gtk_tooltip_get_type
 </SECTION>
 
+<SECTION>
+<FILE>gtktreelistrow</FILE>
+<TITLE>GtkTreeListRow</TITLE>
+gtk_tree_list_row_get_item
+gtk_tree_list_row_set_expanded
+gtk_tree_list_row_get_expanded
+gtk_tree_list_row_is_expandable
+gtk_tree_list_row_get_position
+gtk_tree_list_row_get_depth
+gtk_tree_list_row_get_children
+gtk_tree_list_row_get_parent
+gtk_tree_list_row_get_child_row
+<SUBSECTION Standard>
+GTK_TREE_LIST_ROW
+GTK_IS_TREE_LIST_ROW
+GTK_TYPE_TREE_LIST_ROW
+GTK_TREE_LIST_ROW_CLASS
+GTK_IS_TREE_LIST_ROW_CLASS
+GTK_TREE_LIST_ROW_GET_CLASS
+<SUBSECTION Private>
+gtk_tree_list_row_get_type
+</SECTION>
+
 <SECTION>
 <FILE>gtktreelistmodel</FILE>
 <TITLE>GtkTreeListModel</TITLE>
@@ -3464,18 +3487,6 @@ gtk_tree_list_model_set_autoexpand
 gtk_tree_list_model_get_autoexpand
 gtk_tree_list_model_get_child_row
 gtk_tree_list_model_get_row
-
-<SUBSECTION>
-gtk_tree_list_row_get_item
-gtk_tree_list_row_set_expanded
-gtk_tree_list_row_get_expanded
-gtk_tree_list_row_is_expandable
-gtk_tree_list_row_get_position
-gtk_tree_list_row_get_depth
-gtk_tree_list_row_get_children
-gtk_tree_list_row_get_parent
-gtk_tree_list_row_get_child_row
-
 <SUBSECTION Standard>
 GTK_TREE_LIST_MODEL
 GTK_IS_TREE_LIST_MODEL
@@ -3483,14 +3494,7 @@ GTK_TYPE_TREE_LIST_MODEL
 GTK_TREE_LIST_MODEL_CLASS
 GTK_IS_TREE_LIST_MODEL_CLASS
 GTK_TREE_LIST_MODEL_GET_CLASS
-GTK_TREE_LIST_ROW
-GTK_IS_TREE_LIST_ROW
-GTK_TYPE_TREE_LIST_ROW
-GTK_TREE_LIST_ROW_CLASS
-GTK_IS_TREE_LIST_ROW_CLASS
-GTK_TREE_LIST_ROW_GET_CLASS
 <SUBSECTION Private>
-gtk_tree_list_model_get_type
 gtk_tree_list_row_get_type
 </SECTION>
 
diff --git a/docs/reference/gtk/gtk4.types.in b/docs/reference/gtk/gtk4.types.in
index 7db1dbb345..da3fdbcce2 100644
--- a/docs/reference/gtk/gtk4.types.in
+++ b/docs/reference/gtk/gtk4.types.in
@@ -204,6 +204,7 @@ gtk_tool_button_get_type
 gtk_tool_item_get_type
 gtk_tree_drag_dest_get_type
 gtk_tree_drag_source_get_type
+gtk_tree_expander_get_type
 gtk_tree_list_model_get_type
 gtk_tree_list_row_get_type
 gtk_tree_model_filter_get_type
diff --git a/gtk/gtktreelistmodel.c b/gtk/gtktreelistmodel.c
index 333b8b70e6..597de53c6f 100644
--- a/gtk/gtktreelistmodel.c
+++ b/gtk/gtktreelistmodel.c
@@ -930,7 +930,24 @@ gtk_tree_list_model_get_child_row (GtkTreeListModel *self,
   return tree_node_get_row (child);
 }
 
-/***   ROW   ***/
+/**
+ * SECTION:gtktreelistrow
+ * @Short_description: rows in a tree
+ * @Title: GtkTreeListRow
+ * @See_also: #GtkTreeListModel
+ *
+ * #GtkTreeListRow is the object used by #GtkTreeListModel to
+ * represent items. It allows navigating the model as a tree and
+ * modify the state of rows.
+ *
+ * #GtkTreeListRow instances are created by a #GtkTreeListModel only
+ * when the GtkTreeListModel:passthrough property is not set.
+ *
+ * There are various support objects that can make use of #GtkTreeListRow
+ * objects, such as the #GtkTreeExpander widget that allows displaying
+ * an icon to expand or collapse a row or #GtkTreeListRowSorter that makes
+ * it possible to sort trees properly.
+ */
 
 enum {
   ROW_PROP_0,