Improve section model docs

Mention sections in the list widget overview,
and document the list models that support sections.

diff --git a/docs/reference/gtk/section-list-widget.md b/docs/reference/gtk/section-list-widget.md
index 9ab0be7112ac8dba62b2c489098bafbd97b01aed..41db44ba0f4ded1acb5d71cd72f1b0f93aa04e5c 100644 (file)
--- a/docs/reference/gtk/section-list-widget.md
+++ b/docs/reference/gtk/section-list-widget.md
@@ -196,6 +196,15 @@ The _data table_ style of list is a high density table, similar in style to a
 traditional treeview. Individual cells can be selectable and editable. Use
 the `.data-table` style class.
 
+## Sections
+
+List models can optionally group their items into **_sections_**, by implementing
+the `GtkSectionModel` interface. Both `GtkListView` and `GtkGridView` can
+display headers for sections, by installing a separate **_header factory_**.
+
+Many GTK list models support section inherently, or they pass through the
+section of a model they are wrapping.
+
 ## Comparison to GtkTreeView
 
 Developers familiar with `GtkTreeView` may wonder how this way of doing lists

diff --git a/gtk/gtkfilterlistmodel.c b/gtk/gtkfilterlistmodel.c
index 7e53e52c1190a02d96ac92fbc40710e7426acfa3..a41b19fa6e15964840021dab588c811b48639452 100644 (file)
--- a/gtk/gtkfilterlistmodel.c
+++ b/gtk/gtkfilterlistmodel.c
@@ -34,9 +34,11 @@
  * It hides some elements from the other model according to
  * criteria given by a `GtkFilter`.
  *
- * The model can be set up to do incremental searching, so that
+ * The model can be set up to do incremental filtering, so that
  * filtering long lists doesn't block the UI. See
  * [method@Gtk.FilterListModel.set_incremental] for details.
+ *
+ * `GtkFilterListModel` passes through sections from the underlying model.
  */
 
 enum {

diff --git a/gtk/gtkflattenlistmodel.c b/gtk/gtkflattenlistmodel.c
index f80e80ff6d5512fc1dcb1d39dc358039f2f2b8d4..805fca8b709ee8e271df97b8ad42f30eaab1db9c 100644 (file)
--- a/gtk/gtkflattenlistmodel.c
+++ b/gtk/gtkflattenlistmodel.c
@@ -29,8 +29,8 @@
  *
  * `GtkFlattenListModel` is a list model that concatenates other list models.
  *
- * `GtkFlattenListModel` takes a list model containing list models,
- *  and flattens it into a single model.
+ * `GtkFlattenListModel` takes a list model containing list models, and flattens
+ * it into a single model. Each list model becomes a section in the single model.
  */
 
 enum {

diff --git a/gtk/gtksectionmodel.c b/gtk/gtksectionmodel.c
index a5084ab340ab3bd6356cfb256f16746df298b987..eccbe7236905a6f27d0dad5b3f844354b679d69b 100644 (file)
--- a/gtk/gtksectionmodel.c
+++ b/gtk/gtksectionmodel.c
@@ -26,21 +26,19 @@
 /**
  * GtkSectionModel:
  *
- * `GtkSectionModel` is an interface that adds support for section to list models.
+ * `GtkSectionModel` is an interface that adds support for sections to list models.
  *
- * This support is then used by widgets using list models to be able to group their
- * items into sections.
+ * A `GtkSectionModel` groups successive items into so-called sections. List widgets
+ * like `GtkListView` and `GtkGridView` then allow displaying section headers for
+ * these sections by installing a header factory.
  *
  * Many GTK list models support sections inherently, or they pass through the sections
  * of a model they are wrapping.
  *
- * A `GtkSectionModel` groups successive items into so-called sections. List widgets
- * like `GtkListView` then allow displaying section headers for these sections.
- *
- * When the section groupings of a model changes, the model will emit the
+ * When the section groupings of a model change, the model will emit the
  * [signal@Gtk.SectionModel::sections-changed] signal by calling the
  * [method@Gtk.SectionModel.sections_changed] function. All sections in the given range
- * now need to be queried again.  
+ * then need to be queried again.
  * The [signal@Gio.ListModel::items-changed] signal has the same effect, all sections in
  * that range are invalidated, too.
  *