[gtk] listmodels: Clarify documentation for function prototypes

[Benjamin Otte <otte src gnome org>]

commit 29c700d1c73094715ec510f8677934f27952fcc3
Author: Benjamin Otte <otte redhat com>
Date:   Tue Sep 18 07:27:48 2018 +0200

    listmodels: Clarify documentation for function prototypes
    
    Fixes #1341

 gtk/gtkfilterlistmodel.h | 11 +++++++++++
 gtk/gtkmaplistmodel.c    |  5 +++++
 gtk/gtkmaplistmodel.h    | 11 ++++++++---
 gtk/gtktreelistmodel.h   | 10 +++++++++-
 4 files changed, 33 insertions(+), 4 deletions(-)
---
diff --git a/gtk/gtkfilterlistmodel.h b/gtk/gtkfilterlistmodel.h
index 3ab1601ff5..e1f256ac2d 100644
--- a/gtk/gtkfilterlistmodel.h
+++ b/gtk/gtkfilterlistmodel.h
@@ -36,6 +36,17 @@ G_BEGIN_DECLS
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_FINAL_TYPE (GtkFilterListModel, gtk_filter_list_model, GTK, FILTER_LIST_MODEL, GObject)
 
+/**
+ * GtkFilterListModelFilterFunc:
+ * @item: (type GObject): The item that may be filtered
+ * @user_data: user data
+ *
+ * User function that is called to determine if the @item of the original model should be visible.
+ * If it should be visible, this function must return %TRUE. If the model should filter out the
+ * @item, %FALSE must be returned.
+ *
+ * Returns: %TRUE to keep the item around
+ */
 typedef gboolean (* GtkFilterListModelFilterFunc) (gpointer item, gpointer user_data);
 
 GDK_AVAILABLE_IN_ALL
diff --git a/gtk/gtkmaplistmodel.c b/gtk/gtkmaplistmodel.c
index 6a3de78f8b..6f5e331d80 100644
--- a/gtk/gtkmaplistmodel.c
+++ b/gtk/gtkmaplistmodel.c
@@ -180,6 +180,11 @@ gtk_map_list_model_get_item (GListModel *list,
     }
 
   node->item = self->map_func (g_list_model_get_item (self->model, position), self->user_data);
+  if (!G_TYPE_CHECK_INSTANCE_TYPE (node->item, self->item_type))
+    {
+      g_critical ("Map function returned a %s, but it is not a subtype of the model's type %s",
+                  G_OBJECT_TYPE_NAME (node->item), g_type_name (self->item_type));
+    }
   g_object_add_weak_pointer (node->item, &node->item);
 
   return node->item;
diff --git a/gtk/gtkmaplistmodel.h b/gtk/gtkmaplistmodel.h
index e5c637297a..f0ddcc9524 100644
--- a/gtk/gtkmaplistmodel.h
+++ b/gtk/gtkmaplistmodel.h
@@ -38,12 +38,17 @@ G_DECLARE_FINAL_TYPE (GtkMapListModel, gtk_map_list_model, GTK, MAP_LIST_MODEL,
 
 /**
  * GtkMapListModelMapFunc:
- * @item: (transfer full): The item to map
+ * @item: (type GObject) (transfer full): The item to map
  * @user_data: user data
  *
- * User function that is called to map an @item of the original model.
+ * User function that is called to map an @item of the original model to
+ * an item expected by the map model.
  *
- * Returns: (transfer full): The item to map to. This function may not return %NULL
+ * The returned items must conform to the item type of the model they are
+ * used with.
+ *
+ * Returns: (type GObject) (transfer full): The item to map to.
+ *     This function may not return %NULL
  */
 typedef gpointer (* GtkMapListModelMapFunc) (gpointer item, gpointer user_data);
 
diff --git a/gtk/gtktreelistmodel.h b/gtk/gtktreelistmodel.h
index fd9585e2be..40c4d57262 100644
--- a/gtk/gtktreelistmodel.h
+++ b/gtk/gtktreelistmodel.h
@@ -41,11 +41,19 @@ G_DECLARE_FINAL_TYPE (GtkTreeListRow, gtk_tree_list_row, GTK, TREE_LIST_ROW, GOb
 
 /**
  * GtkTreeListModelCreateModelFunc:
- * @item: The item that is expaned
+ * @item: (type GObject): The item that is being expanded
  * @user_data: User data passed when registering the function
  *
  * Prototype of the function called to create new child models when
  * gtk_tree_list_row_set_expanded() is called.
+ *
+ * This function can return %NULL to indicate that @item is guaranteed to be
+ * a leave node and will never have children.  
+ * If it does not have children but may get children later, it should return
+ * an empty model that is filled once children arrive.
+ *
+ * Returns: (nullable): The model tracking the children of @item or %NULL if
+ *     @item can never have children
  */
 typedef GListModel * (* GtkTreeListModelCreateModelFunc) (gpointer item, gpointer user_data);