[devhelp] Book: more logical functions order

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

commit 1c9a935ecea3fd575f082b1af694166b74621538
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Thu Dec 21 13:33:57 2017 +0100

    Book: more logical functions order

 docs/reference/devhelp-sections.txt |    8 +-
 src/dh-book.c                       |  154 +++++++++++++++++-----------------
 src/dh-book.h                       |   13 ++--
 3 files changed, 88 insertions(+), 87 deletions(-)
---
diff --git a/docs/reference/devhelp-sections.txt b/docs/reference/devhelp-sections.txt
index 1bbdac7..aa17a3e 100644
--- a/docs/reference/devhelp-sections.txt
+++ b/docs/reference/devhelp-sections.txt
@@ -28,13 +28,13 @@ dh_assistant_view_get_type
 <FILE>dh-book</FILE>
 DhBook
 dh_book_new
-dh_book_get_links
-dh_book_get_completions
-dh_book_get_tree
+dh_book_get_index_file
 dh_book_get_id
 dh_book_get_title
 dh_book_get_language
-dh_book_get_index_file
+dh_book_get_links
+dh_book_get_tree
+dh_book_get_completions
 dh_book_get_enabled
 dh_book_set_enabled
 dh_book_cmp_by_path
diff --git a/src/dh-book.c b/src/dh-book.c
index e65cad2..356a7d1 100644
--- a/src/dh-book.c
+++ b/src/dh-book.c
@@ -376,15 +376,13 @@ dh_book_new (GFile *index_file)
 }
 
 /**
- * dh_book_get_links:
+ * dh_book_get_index_file:
  * @book: a #DhBook.
  *
- * Returns: (element-type DhLink) (transfer none) (nullable): the list of
- * <emphasis>all</emphasis> #DhLink's part of @book, or %NULL if the book is
- * disabled.
+ * Returns: (transfer none): the index file.
  */
-GList *
-dh_book_get_links (DhBook *book)
+GFile *
+dh_book_get_index_file (DhBook *book)
 {
         DhBookPrivate *priv;
 
@@ -392,18 +390,21 @@ dh_book_get_links (DhBook *book)
 
         priv = dh_book_get_instance_private (book);
 
-        return priv->enabled ? priv->links : NULL;
+        return priv->index_file;
 }
 
 /**
- * dh_book_get_completions:
+ * dh_book_get_id:
  * @book: a #DhBook.
  *
- * Returns: (element-type utf8) (transfer none) (nullable): the completions
- * associated with the book.
+ * Gets the book ID. In the Devhelp index file format version 2, it is actually
+ * the “name”, not the ID, but “book ID” is clearer, “book name” can be confused
+ * with the title.
+ *
+ * Returns: the book ID.
  */
-GList *
-dh_book_get_completions (DhBook *book)
+const gchar *
+dh_book_get_id (DhBook *book)
 {
         DhBookPrivate *priv;
 
@@ -411,53 +412,17 @@ dh_book_get_completions (DhBook *book)
 
         priv = dh_book_get_instance_private (book);
 
-        if (!priv->enabled)
-                return NULL;
-
-        if (priv->completions == NULL) {
-                GList *l;
-
-                for (l = priv->links; l != NULL; l = l->next) {
-                        DhLink *link = l->data;
-                        gchar *str;
-
-                        /* Add additional "page:" and "book:" completions.
-                         * FIXME: broken, doesn't match what DhKeywordModel
-                         * does. But maybe the feature will be removed, see:
-                         * https://bugzilla.gnome.org/show_bug.cgi?id=791442
-                         */
-                        if (dh_link_get_link_type (link) == DH_LINK_TYPE_BOOK) {
-                                str = g_strdup_printf ("book:%s", dh_link_get_name (link));
-                                priv->completions = g_list_prepend (priv->completions, str);
-                        }
-                        else if (dh_link_get_link_type (link) == DH_LINK_TYPE_PAGE) {
-                                str = g_strdup_printf ("page:%s", dh_link_get_name (link));
-                                priv->completions = g_list_prepend (priv->completions, str);
-                        }
-
-                        str = g_strdup (dh_link_get_name (link));
-                        priv->completions = g_list_prepend (priv->completions, str);
-                }
-        }
-
-        return priv->completions;
+        return priv->id;
 }
 
 /**
- * dh_book_get_tree:
+ * dh_book_get_title:
  * @book: a #DhBook.
  *
- * Gets the general structure of the book, as a tree. The tree contains only
- * #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_links().
- *
- * Returns: (transfer none) (nullable): the tree of #DhLink's part of the @book,
- * or %NULL if the book is disabled.
+ * Returns: the book title.
  */
-GNode *
-dh_book_get_tree (DhBook *book)
+const gchar *
+dh_book_get_title (DhBook *book)
 {
         DhBookPrivate *priv;
 
@@ -465,21 +430,17 @@ dh_book_get_tree (DhBook *book)
 
         priv = dh_book_get_instance_private (book);
 
-        return priv->enabled ? priv->tree : NULL;
+        return priv->title;
 }
 
 /**
- * dh_book_get_id:
+ * dh_book_get_language:
  * @book: a #DhBook.
  *
- * Gets the book ID. In the Devhelp index file format version 2, it is actually
- * the “name”, not the ID, but “book ID” is clearer, “book name” can be confused
- * with the title.
- *
- * Returns: the book ID.
+ * Returns: the book language.
  */
 const gchar *
-dh_book_get_id (DhBook *book)
+dh_book_get_language (DhBook *book)
 {
         DhBookPrivate *priv;
 
@@ -487,17 +448,19 @@ dh_book_get_id (DhBook *book)
 
         priv = dh_book_get_instance_private (book);
 
-        return priv->id;
+        return priv->language;
 }
 
 /**
- * dh_book_get_title:
+ * dh_book_get_links:
  * @book: a #DhBook.
  *
- * Returns: the book title.
+ * Returns: (element-type DhLink) (transfer none) (nullable): the list of
+ * <emphasis>all</emphasis> #DhLink's part of @book, or %NULL if the book is
+ * disabled.
  */
-const gchar *
-dh_book_get_title (DhBook *book)
+GList *
+dh_book_get_links (DhBook *book)
 {
         DhBookPrivate *priv;
 
@@ -505,17 +468,24 @@ dh_book_get_title (DhBook *book)
 
         priv = dh_book_get_instance_private (book);
 
-        return priv->title;
+        return priv->enabled ? priv->links : NULL;
 }
 
 /**
- * dh_book_get_language:
+ * dh_book_get_tree:
  * @book: a #DhBook.
  *
- * Returns: the book language.
+ * Gets the general structure of the book, as a tree. The tree contains only
+ * #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_links().
+ *
+ * Returns: (transfer none) (nullable): the tree of #DhLink's part of the @book,
+ * or %NULL if the book is disabled.
  */
-const gchar *
-dh_book_get_language (DhBook *book)
+GNode *
+dh_book_get_tree (DhBook *book)
 {
         DhBookPrivate *priv;
 
@@ -523,17 +493,18 @@ dh_book_get_language (DhBook *book)
 
         priv = dh_book_get_instance_private (book);
 
-        return priv->language;
+        return priv->enabled ? priv->tree : NULL;
 }
 
 /**
- * dh_book_get_index_file:
+ * dh_book_get_completions:
  * @book: a #DhBook.
  *
- * Returns: (transfer none): the index file.
+ * Returns: (element-type utf8) (transfer none) (nullable): the completions
+ * associated with the book.
  */
-GFile *
-dh_book_get_index_file (DhBook *book)
+GList *
+dh_book_get_completions (DhBook *book)
 {
         DhBookPrivate *priv;
 
@@ -541,7 +512,36 @@ dh_book_get_index_file (DhBook *book)
 
         priv = dh_book_get_instance_private (book);
 
-        return priv->index_file;
+        if (!priv->enabled)
+                return NULL;
+
+        if (priv->completions == NULL) {
+                GList *l;
+
+                for (l = priv->links; l != NULL; l = l->next) {
+                        DhLink *link = l->data;
+                        gchar *str;
+
+                        /* Add additional "page:" and "book:" completions.
+                         * FIXME: broken, doesn't match what DhKeywordModel
+                         * does. But maybe the feature will be removed, see:
+                         * https://bugzilla.gnome.org/show_bug.cgi?id=791442
+                         */
+                        if (dh_link_get_link_type (link) == DH_LINK_TYPE_BOOK) {
+                                str = g_strdup_printf ("book:%s", dh_link_get_name (link));
+                                priv->completions = g_list_prepend (priv->completions, str);
+                        }
+                        else if (dh_link_get_link_type (link) == DH_LINK_TYPE_PAGE) {
+                                str = g_strdup_printf ("page:%s", dh_link_get_name (link));
+                                priv->completions = g_list_prepend (priv->completions, str);
+                        }
+
+                        str = g_strdup (dh_link_get_name (link));
+                        priv->completions = g_list_prepend (priv->completions, str);
+                }
+        }
+
+        return priv->completions;
 }
 
 /**
diff --git a/src/dh-book.h b/src/dh-book.h
index d14d544..f0ad9d5 100644
--- a/src/dh-book.h
+++ b/src/dh-book.h
@@ -4,6 +4,7 @@
  * Copyright (C) 2002 Mikael Hallendal <micke imendio com>
  * Copyright (C) 2005-2008 Imendio AB
  * Copyright (C) 2010 Lanedo GmbH
+ * Copyright (C) 2017 Sébastien Wilmet <swilmet gnome org>
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
@@ -48,11 +49,7 @@ GType        dh_book_get_type        (void) G_GNUC_CONST;
 
 DhBook *     dh_book_new             (GFile *index_file);
 
-GList *      dh_book_get_links       (DhBook *book);
-
-GList *      dh_book_get_completions (DhBook *book);
-
-GNode *      dh_book_get_tree        (DhBook *book);
+GFile *      dh_book_get_index_file  (DhBook *book);
 
 const gchar *dh_book_get_id          (DhBook *book);
 
@@ -60,7 +57,11 @@ const gchar *dh_book_get_title       (DhBook *book);
 
 const gchar *dh_book_get_language    (DhBook *book);
 
-GFile *      dh_book_get_index_file  (DhBook *book);
+GList *      dh_book_get_links       (DhBook *book);
+
+GNode *      dh_book_get_tree        (DhBook *book);
+
+GList *      dh_book_get_completions (DhBook *book);
 
 gboolean     dh_book_get_enabled     (DhBook *book);