[devhelp/wip/swilmet/book: 2/2] Book: fix/improve the gtk-doc comments

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

commit 3ef17b260cae4835df5c57edac2f805e5fa85ec7
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Apr 29 12:18:14 2017 +0200

    Book: fix/improve the gtk-doc comments

 src/dh-book.c |   22 +++++++++-------------
 1 files changed, 9 insertions(+), 13 deletions(-)
---
diff --git a/src/dh-book.c b/src/dh-book.c
index cb21513..a8db698 100644
--- a/src/dh-book.c
+++ b/src/dh-book.c
@@ -224,9 +224,7 @@ unref_node_link (GNode    *node,
  * dh_book_new:
  * @book_path: the path of the book
  *
- * Create a new #DhBook object.
- *
- * Returns: a new #DhBook object
+ * Returns: a new #DhBook object.
  */
 DhBook *
 dh_book_new (const gchar *book_path)
@@ -370,11 +368,10 @@ book_monitor_event_cb (GFileMonitor      *file_monitor,
 
 /**
  * dh_book_get_keywords:
- * @book: a #DhBook object
- *
- * Get the #GList of keywords associated with the book.
+ * @book: a #DhBook.
  *
- * Returns: (element-type utf8) (transfer none) (nullable): the keywords associated with the book
+ * Returns: (element-type DhLink) (transfer none) (nullable): the list of
+ * #DhLink's part of @book.
  */
 GList *
 dh_book_get_keywords (DhBook *book)
@@ -390,11 +387,10 @@ dh_book_get_keywords (DhBook *book)
 
 /**
  * dh_book_get_completions:
- * @book: a #DhBook object
- *
- * Get the #GList of completions associated with the book.
+ * @book: a #DhBook.
  *
- * Returns: (element-type utf8) (transfer full) (nullable): the completions associated with the book
+ * Returns: (element-type utf8) (transfer none) (nullable): the completions
+ * associated with the book.
  */
 GList *
 dh_book_get_completions (DhBook *book)
@@ -435,11 +431,11 @@ dh_book_get_completions (DhBook *book)
 
 /**
  * dh_book_get_tree:
- * @book: a #DhBook object
+ * @book: a #DhBook.
  *
  * Get the #GNode representing the book tree.
  *
- * Returns: (transfer none) (nullable): the book tree
+ * Returns: (transfer none) (nullable): the tree of #DhLink's part of the @book.
  */
 GNode *
 dh_book_get_tree (DhBook *book)