[devhelp] docs: improve docs for dh_book_get_tree() and dh_book_get_keywords()

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

commit 276b25d35aee8d1e61f26a9323aa6687f34e6611
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun May 7 11:53:02 2017 +0200

    docs: improve docs for dh_book_get_tree() and dh_book_get_keywords()
    
    The GList of keywords and the GNode are created in dh-parser.c. The
    GNode doesn't contain all DhLinks, it's something worth explaining.

 src/dh-book.c |   12 ++++++++++--
 1 files changed, 10 insertions(+), 2 deletions(-)
---
diff --git a/src/dh-book.c b/src/dh-book.c
index e6765de..9615995 100644
--- a/src/dh-book.c
+++ b/src/dh-book.c
@@ -363,7 +363,8 @@ dh_book_new (const gchar *book_path)
  * @book: a #DhBook.
  *
  * Returns: (element-type DhLink) (transfer none) (nullable): the list of
- * #DhLink's part of @book.
+ * <emphasis>all</emphasis> #DhLink's part of @book, or %NULL if the book is
+ * disabled.
  */
 GList *
 dh_book_get_keywords (DhBook *book)
@@ -425,7 +426,14 @@ dh_book_get_completions (DhBook *book)
  * dh_book_get_tree:
  * @book: a #DhBook.
  *
- * Returns: (transfer none) (nullable): the tree of #DhLink's part of the @book.
+ * 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 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().
+ *
+ * Returns: (transfer none) (nullable): the tree of #DhLink's part of the @book,
+ * or %NULL if the book is disabled.
  */
 GNode *
 dh_book_get_tree (DhBook *book)