[devhelp] docs: write class descriptions for the "Side Panel" part

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

commit faf8c125f48c31fdfa5e950a3d4e24f1acf8e145
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun May 7 13:11:54 2017 +0200

    docs: write class descriptions for the "Side Panel" part

 docs/reference/devhelp-sections.txt |    3 ---
 src/dh-book-tree.c                  |   17 +++++++++++++++++
 src/dh-book.c                       |    2 +-
 src/dh-keyword-model.c              |   12 ++++++++++++
 src/dh-sidebar.c                    |   25 +++++++++++++++++++++++++
 5 files changed, 55 insertions(+), 4 deletions(-)
---
diff --git a/docs/reference/devhelp-sections.txt b/docs/reference/devhelp-sections.txt
index 0c353c4..a994e69 100644
--- a/docs/reference/devhelp-sections.txt
+++ b/docs/reference/devhelp-sections.txt
@@ -72,7 +72,6 @@ dh_book_manager_get_type
 
 <SECTION>
 <FILE>dh-book-tree</FILE>
-<TITLE>DhBookTree</TITLE>
 DhBookTree
 dh_book_tree_new
 dh_book_tree_select_uri
@@ -89,7 +88,6 @@ dh_book_tree_get_type
 
 <SECTION>
 <FILE>dh-keyword-model</FILE>
-<TITLE>DhKeywordModel</TITLE>
 DhKeywordModel
 dh_keyword_model_new
 dh_keyword_model_filter
@@ -134,7 +132,6 @@ dh_link_type_get_type
 
 <SECTION>
 <FILE>dh-sidebar</FILE>
-<TITLE>DhSidebar</TITLE>
 DhSidebar
 dh_sidebar_new
 dh_sidebar_get_selected_book
diff --git a/src/dh-book-tree.c b/src/dh-book-tree.c
index f24bd0c..9263d36 100644
--- a/src/dh-book-tree.c
+++ b/src/dh-book-tree.c
@@ -26,6 +26,23 @@
 #include "dh-book-manager.h"
 #include "dh-book.h"
 
+/**
+ * SECTION:dh-book-tree
+ * @Title: DhBookTree
+ * @Short_description: A #GtkTreeView containing the tree structure of all
+ * enabled #DhBook's
+ *
+ * #DhBookTree is a #GtkTreeView (showing a tree, not a list) containing the
+ * general tree structure of all enabled #DhBook's.
+ *
+ * The dh_book_get_tree() function is called to get the tree structure of a
+ * #DhBook. As such the tree contains only #DhLink's of type %DH_LINK_TYPE_BOOK
+ * or %DH_LINK_TYPE_PAGE.
+ *
+ * When an element is selected, the #DhBookTree::link-selected signal is
+ * emitted. Only one element can be selected at a time.
+ */
+
 typedef struct {
         const gchar *uri;
         GtkTreeIter  iter;
diff --git a/src/dh-book.c b/src/dh-book.c
index 9615995..41b19a2 100644
--- a/src/dh-book.c
+++ b/src/dh-book.c
@@ -427,7 +427,7 @@ dh_book_get_completions (DhBook *book)
  * @book: a #DhBook.
  *
  * Gets the general structure of the book, as a tree. The tree contains only
- * #DhLink's with type %DH_LINK_TYPE_BOOK or %DH_LINK_TYPE_PAGE. The other
+ * #DhLink's of type %DH_LINK_TYPE_BOOK or %DH_LINK_TYPE_PAGE. The other
  * #DhLink's are not contained in the tree. To have a list of
  * <emphasis>all</emphasis> #DhLink's part of the book, you need to call
  * dh_book_get_keywords().
diff --git a/src/dh-keyword-model.c b/src/dh-keyword-model.c
index 3ffe1eb..35bd0ef 100644
--- a/src/dh-keyword-model.c
+++ b/src/dh-keyword-model.c
@@ -29,6 +29,18 @@
 #include "dh-book.h"
 #include "dh-util.h"
 
+/**
+ * SECTION:dh-keyword-model
+ * @Title: DhKeywordModel
+ * @Short_description: A custom #GtkTreeModel implementation for searching a
+ * keyword
+ *
+ * #DhKeywordModel is a custom #GtkTreeModel implementation (as a list, not a
+ * tree) for searching a keyword.
+ *
+ * The dh_keyword_model_filter() function is used to set the search criteria.
+ */
+
 typedef struct {
         gchar *current_book_id;
 
diff --git a/src/dh-sidebar.c b/src/dh-sidebar.c
index c269ee3..80c459c 100644
--- a/src/dh-sidebar.c
+++ b/src/dh-sidebar.c
@@ -30,6 +30,31 @@
 #include "dh-book.h"
 #include "dh-book-tree.h"
 
+/**
+ * SECTION:dh-sidebar
+ * @Title: DhSidebar
+ * @Short_description: The sidebar
+ *
+ * In the Devhelp application, there is one #DhSidebar per main window,
+ * displayed in the left side panel.
+ *
+ * A #DhSidebar contains:
+ * - a #GtkSearchEntry at the top;
+ * - a #DhBookTree (a subclass of #GtkTreeView);
+ * - another #GtkTreeView (displaying a list, not a tree) with a #DhKeywordModel
+ *   as its model.
+ *
+ * When the #GtkSearchEntry is empty, the #DhBookTree is shown. When the
+ * #GtkSearchEntry is not empty, it shows the search results in the other
+ * #GtkTreeView. The two #GtkTreeView's cannot be both visible at the same time,
+ * it's either one or the other.
+ *
+ * The #DhSidebar::link-selected signal is emitted when one element in one of
+ * the #GtkTreeView's is selected. When that happens, the Devhelp application
+ * opens the link in a #WebKitWebView shown at the right side of the main
+ * window.
+ */
+
 typedef struct {
         DhBookTree              *book_tree;
         GtkScrolledWindow       *sw_book_tree;