Merge branch 'matthiasc/for-main' into 'main'

Improve section model docs

See merge request GNOME/gtk!6003

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

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 {

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 {

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.
  *