[tepl/wip/tab] Tab: update docs

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

commit 871998e43b900f4c8ce3fd4cabf2d3690bbc2044
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Wed Jun 21 16:01:59 2017 +0200

    Tab: update docs

 tepl/tepl-tab.c |   17 ++++++++++++-----
 1 files changed, 12 insertions(+), 5 deletions(-)
---
diff --git a/tepl/tepl-tab.c b/tepl/tepl-tab.c
index 80c8fb9..c8398be 100644
--- a/tepl/tepl-tab.c
+++ b/tepl/tepl-tab.c
@@ -22,12 +22,18 @@
 
 /**
  * SECTION:tab
- * @Short_description: Contains a TeplView with GtkInfoBars on top
+ * @Short_description: Contains a TeplView and GtkInfoBars
  * @Title: TeplTab
  *
- * A #GtkGrid container that contains a #TeplView, and one or several
- * #GtkInfoBar's can be added on top. By default #TeplTab has a vertical
- * #GtkOrientation.
+ * #TeplTab is meant to be the content of one tab in the text editor (if the
+ * text editor has a Tabbed Document Interface). It is a #GtkGrid container that
+ * contains the #TeplView and can contain one or several #GtkInfoBar's.
+ *
+ * By default:
+ * - #TeplTab has a vertical #GtkOrientation.
+ * - The main child widget of #TeplTab is a #GtkScrolledWindow which contains
+ *   the #TeplView.
+ * - #GtkInfoBar's are added on top of the #GtkScrolledWindow.
  *
  * The way that the #TeplView is packed into the #TeplTab is customizable with
  * the ::pack_view virtual function. Similarly, the way that #GtkInfoBar's are
@@ -205,7 +211,8 @@ tepl_tab_class_init (TeplTabClass *klass)
        /**
         * TeplTab:view:
         *
-        * The #TeplView contained in the tab.
+        * The #TeplView contained in the tab. When this property is set, the
+        * ::pack_view virtual function is called.
         *
         * Since: 3.0
         */