[devhelp] docs: improve the docs of the new libdevhelp classes

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

commit 8955496e92f27e1c0cdc4ee71639e2a12419168f
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Mon Jun 18 20:17:40 2018 +0200

    docs: improve the docs of the new libdevhelp classes

 devhelp/dh-notebook.c  |  3 +++
 devhelp/dh-tab-label.c |  3 +++
 devhelp/dh-web-view.c  | 19 +++++++++++++++----
 3 files changed, 21 insertions(+), 4 deletions(-)
---
diff --git a/devhelp/dh-notebook.c b/devhelp/dh-notebook.c
index 763c9867..e31bd043 100644
--- a/devhelp/dh-notebook.c
+++ b/devhelp/dh-notebook.c
@@ -28,6 +28,9 @@
  *
  * #DhNotebook is a subclass of #GtkNotebook. The content of the tabs are
  * #DhTab's, and the tab labels are #DhTabLabel's.
+ *
+ * #DhNotebook handles the #DhWebView::open-new-tab signal by appending a new
+ * #DhTab.
  */
 
 struct _DhNotebookPrivate {
diff --git a/devhelp/dh-tab-label.c b/devhelp/dh-tab-label.c
index 70af9d6c..32844a8f 100644
--- a/devhelp/dh-tab-label.c
+++ b/devhelp/dh-tab-label.c
@@ -27,6 +27,9 @@
  * @Short_description: A #DhTab label, used by #DhNotebook
  *
  * The #DhTabLabel widget is used for the tab labels in #DhNotebook.
+ *
+ * It contains the title as returned by dh_web_view_get_devhelp_title(), plus a
+ * close button.
  */
 
 struct _DhTabLabelPrivate {
diff --git a/devhelp/dh-web-view.c b/devhelp/dh-web-view.c
index 1f73eb54..cfc907cb 100644
--- a/devhelp/dh-web-view.c
+++ b/devhelp/dh-web-view.c
@@ -30,14 +30,21 @@
  * @Short_description: Subclass of #WebKitWebView
  *
  * #DhWebView is a subclass of #WebKitWebView, to have a higher-level API for
- * some features.
+ * some features, and with some customizations for the libdevhelp use-case.
+ *
+ * Features:
+ * - Ctrl+scroll to zoom in/zoom out.
+ * - Sending the #DhWebView::open-new-tab signal on middle click or Ctrl+click
+ *   on a link (#DhNotebook handles that signal).
+ * - Calls gtk_show_uri_on_window() when opening a non-local link (for example a
+ *   `http://` URL).
  *
  * The #DhProfile is used for:
  * - Applying the #DhSettings fonts.
  * - When trying to load a remote URL from developer.gnome.org, find in the
- *   #DhBookList if there is an equivalent local link.
+ *   #DhBookList if there is an equivalent local link to load it instead of
+ *   opening the URL with gtk_show_uri_on_window().
  */
-/* TODO document all the features. */
 
 struct _DhWebViewPrivate {
         DhProfile *profile;
@@ -625,7 +632,11 @@ dh_web_view_get_profile (DhWebView *view)
  * dh_web_view_get_devhelp_title:
  * @view: a #DhWebView.
  *
- * Returns: the @view title suitable for a tab label or window title.
+ * An enhanced getter function for the #WebKitWebView:title property: when that
+ * property is the empty string or %NULL, this function returns “Empty Page”
+ * (translated).
+ *
+ * Returns: the title of @view, suitable for a tab label or window title.
  * Since: 3.30
  */
 const gchar *