[tepl: 2/2] TabList: document that non-TeplTab children are skipped in the GList

[Sébastien Wilmet <swilmet src gnome org>]

commit 260fdac18b99d3f1a76e3a19437ed83909ce53c0
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Jun 24 15:35:53 2017 +0200

    TabList: document that non-TeplTab children are skipped in the GList
    
    At least that's what TeplNotebook does.

 tepl/tepl-tab-list.c |   15 +++++++++++----
 tepl/tepl-tab-list.h |    5 ++++-
 2 files changed, 15 insertions(+), 5 deletions(-)
---
diff --git a/tepl/tepl-tab-list.c b/tepl/tepl-tab-list.c
index 0b84ba5..5e6dabf 100644
--- a/tepl/tepl-tab-list.c
+++ b/tepl/tepl-tab-list.c
@@ -58,6 +58,13 @@ tepl_tab_list_default_init (TeplTabListInterface *interface)
  * tepl_tab_list_get_tabs:
  * @tab_list: a #TeplTabList.
  *
+ * Gets the list of #TeplTab's contained in @tab_list.
+ *
+ * If @tab_list contains non-#TeplTab children, those will not be present in the
+ * returned list. In other words, it is <emphasis>not</emphasis> guaranteed that
+ * the index of a #TeplTab in the returned #GList has the same child index in
+ * the @tab_list container.
+ *
  * Returns: (transfer container) (element-type TeplTab): the list of all the
  * #TeplTab's contained in @tab_list.
  * Since: 3.0
@@ -76,8 +83,8 @@ tepl_tab_list_get_tabs (TeplTabList *tab_list)
  *
  * Convenience function.
  *
- * Returns: (transfer container) (element-type TeplView): the list of all the
- * #TeplView's contained in @tab_list.
+ * Returns: (transfer container) (element-type TeplView): like
+ * tepl_tab_list_get_tabs(), but returns #TeplView's.
  * Since: 3.0
  */
 GList *
@@ -109,8 +116,8 @@ tepl_tab_list_get_views (TeplTabList *tab_list)
  *
  * Convenience function.
  *
- * Returns: (transfer container) (element-type TeplBuffer): the list of all the
- * #TeplBuffer's contained in @tab_list.
+ * Returns: (transfer container) (element-type TeplBuffer): like
+ * tepl_tab_list_get_tabs(), but returns #TeplBuffer's.
  * Since: 3.0
  */
 GList *
diff --git a/tepl/tepl-tab-list.h b/tepl/tepl-tab-list.h
index e713c57..bd076dc 100644
--- a/tepl/tepl-tab-list.h
+++ b/tepl/tepl-tab-list.h
@@ -40,7 +40,10 @@ typedef struct _TeplTabListInterface TeplTabListInterface;
  * TeplTabListInterface:
  * @parent_interface: The parent interface.
  * @get_tabs: Virtual function pointer for tepl_tab_list_get_tabs(). By default,
- *   %NULL is returned.
+ *   %NULL is returned. When implementing this vfunc, #GList nodes must be
+ *   created only for #TeplTab children; if the #TeplTabList contains a
+ *   non-#TeplTab child, it must be skipped. See the documentation of
+ *   tepl_tab_list_get_tabs().
  * @get_active_tab: Virtual function pointer for tepl_tab_list_get_active_tab().
  *   By default, %NULL is returned.
  *