[devhelp] DhLink: more logical function order

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

commit c963d35ae27fd3950dade661f9590120b0a3f5ba
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Jun 4 15:30:53 2017 +0200

    DhLink: more logical function order
    
    1. constructor
    2. ref/unref
    3. what concerns directly the link itself
    4. what concerns the book the link is contained in
    5. compare and to_string
    
    Also, space out the functions in the header. IMHO it's a little more
    readable.

 docs/reference/devhelp-sections.txt |   12 +-
 src/dh-link.c                       |  222 +++++++++++++++++-----------------
 src/dh-link.h                       |   29 ++++--
 3 files changed, 138 insertions(+), 125 deletions(-)
---
diff --git a/docs/reference/devhelp-sections.txt b/docs/reference/devhelp-sections.txt
index 465372c..cf65125 100644
--- a/docs/reference/devhelp-sections.txt
+++ b/docs/reference/devhelp-sections.txt
@@ -111,15 +111,15 @@ DhLinkFlags
 dh_link_new
 dh_link_ref
 dh_link_unref
-dh_link_compare
+dh_link_get_link_type
+dh_link_get_flags
+dh_link_set_flags
 dh_link_get_name
-dh_link_get_book_name
 dh_link_get_file_name
-dh_link_get_book_id
 dh_link_get_uri
-dh_link_get_flags
-dh_link_set_flags
-dh_link_get_link_type
+dh_link_get_book_name
+dh_link_get_book_id
+dh_link_compare
 dh_link_type_to_string
 <SUBSECTION Standard>
 DH_TYPE_LINK
diff --git a/src/dh-link.c b/src/dh-link.c
index 8bcf609..751e035 100644
--- a/src/dh-link.c
+++ b/src/dh-link.c
@@ -137,64 +137,6 @@ dh_link_new (DhLinkType   type,
 }
 
 /**
- * dh_link_compare:
- * @a: (type DhLink): a #DhLink.
- * @b: (type DhLink): a #DhLink.
- *
- * Compares the links @a and @b. This function is used to determine in which
- * order the links should be displayed.
- *
- * Returns: an integer less than zero if @a should appear before @b; zero if
- * there are no preferences; an integer greater than zero if @b should appear
- * before @a.
- */
-gint
-dh_link_compare (gconstpointer a,
-                 gconstpointer b)
-{
-        DhLink *la = (DhLink *) a;
-        DhLink *lb = (DhLink *) b;
-        gint flags_diff;
-        gint diff;
-
-        g_return_val_if_fail (a != NULL, 0);
-        g_return_val_if_fail (b != NULL, 0);
-
-        /* Sort deprecated hits last. */
-        flags_diff = ((la->flags & DH_LINK_FLAGS_DEPRECATED) -
-                      (lb->flags & DH_LINK_FLAGS_DEPRECATED));
-        if (flags_diff != 0)
-                return flags_diff;
-
-        /* Collation-based sorting */
-        if (G_UNLIKELY (la->name_collation_key == NULL))
-                la->name_collation_key = g_utf8_collate_key (la->name, -1);
-        if (G_UNLIKELY (lb->name_collation_key == NULL))
-                lb->name_collation_key = g_utf8_collate_key (lb->name, -1);
-
-        diff = strcmp (la->name_collation_key,
-                       lb->name_collation_key);
-
-        /* For the same names, sort page links before other links. The page is
-         * more important than a symbol (typically contained in that page).
-         */
-        if (diff == 0) {
-                if (la->type == lb->type)
-                        return 0;
-
-                if (la->type == DH_LINK_TYPE_PAGE)
-                        return -1;
-
-                if (lb->type == DH_LINK_TYPE_PAGE)
-                        return 1;
-
-                return 0;
-        }
-
-        return diff;
-}
-
-/**
  * dh_link_ref:
  * @link: a #DhLink.
  *
@@ -230,72 +172,79 @@ dh_link_unref (DhLink *link)
 }
 
 /**
- * dh_link_get_name:
+ * dh_link_get_link_type:
  * @link: a #DhLink.
  *
- * Returns: the name of the @link.
+ * Returns: the #DhLinkType of @link.
  */
-const gchar *
-dh_link_get_name (DhLink *link)
+DhLinkType
+dh_link_get_link_type (DhLink *link)
 {
-        g_return_val_if_fail (link != NULL, NULL);
+        g_return_val_if_fail (link != NULL, 0);
 
-        return link->name;
+        return link->type;
 }
 
 /**
- * dh_link_get_book_name:
+ * dh_link_get_flags:
  * @link: a #DhLink.
  *
- * Returns: the name of the book that the @link is contained in.
+ * Returns: the #DhLinkFlags of @link.
  */
-const gchar *
-dh_link_get_book_name (DhLink *link)
+DhLinkFlags
+dh_link_get_flags (DhLink *link)
 {
-        g_return_val_if_fail (link != NULL, NULL);
+        g_return_val_if_fail (link != NULL, DH_LINK_FLAGS_NONE);
 
-        if (link->book != NULL)
-                return link->book->name;
+        return link->flags;
+}
 
-        return "";
+/**
+ * dh_link_set_flags:
+ * @link: a #DhLink.
+ * @flags: the new flags of the link.
+ *
+ * Sets the flags of the link.
+ */
+void
+dh_link_set_flags (DhLink      *link,
+                   DhLinkFlags  flags)
+{
+        g_return_if_fail (link != NULL);
+
+        link->flags = flags;
 }
 
 /**
- * dh_link_get_file_name:
+ * dh_link_get_name:
  * @link: a #DhLink.
  *
- * Returns: the name of the file that the @link is contained in.
+ * Returns: the name of the @link.
  */
 const gchar *
-dh_link_get_file_name (DhLink *link)
+dh_link_get_name (DhLink *link)
 {
         g_return_val_if_fail (link != NULL, NULL);
 
-        /* Return filename if the link is itself a page or if the link is within
-         * a page (i.e. every link type except a book).
-         */
-        if (link->type != DH_LINK_TYPE_BOOK)
-                return link->relative_url;
-
-        return "";
+        return link->name;
 }
 
 /**
- * dh_link_get_book_id:
+ * dh_link_get_file_name:
  * @link: a #DhLink.
  *
- * Returns: the book ID.
+ * Returns: the name of the file that the @link is contained in.
  */
 const gchar *
-dh_link_get_book_id (DhLink *link)
+dh_link_get_file_name (DhLink *link)
 {
         g_return_val_if_fail (link != NULL, NULL);
 
-        if (link->type == DH_LINK_TYPE_BOOK)
-                return link->book_id;
-
-        if (link->book != NULL)
-                return link->book->book_id;
+        /* Return filename if the link is itself a page or if the link is within
+         * a page (i.e. every link type except a book).
+         */
+        if (link->type != DH_LINK_TYPE_BOOK)
+                return link->relative_url;
 
         return "";
 }
@@ -344,47 +293,98 @@ dh_link_get_uri (DhLink *link)
 }
 
 /**
- * dh_link_get_link_type:
+ * dh_link_get_book_name:
  * @link: a #DhLink.
  *
- * Returns: the #DhLinkType of @link.
+ * Returns: the name of the book that the @link is contained in.
  */
-DhLinkType
-dh_link_get_link_type (DhLink *link)
+const gchar *
+dh_link_get_book_name (DhLink *link)
 {
-        g_return_val_if_fail (link != NULL, 0);
+        g_return_val_if_fail (link != NULL, NULL);
 
-        return link->type;
+        if (link->book != NULL)
+                return link->book->name;
+
+        return "";
 }
 
 /**
- * dh_link_get_flags:
+ * dh_link_get_book_id:
  * @link: a #DhLink.
  *
- * Returns: the #DhLinkFlags of @link.
+ * Returns: the book ID.
  */
-DhLinkFlags
-dh_link_get_flags (DhLink *link)
+const gchar *
+dh_link_get_book_id (DhLink *link)
 {
-        g_return_val_if_fail (link != NULL, DH_LINK_FLAGS_NONE);
+        g_return_val_if_fail (link != NULL, NULL);
 
-        return link->flags;
+        if (link->type == DH_LINK_TYPE_BOOK)
+                return link->book_id;
+
+        if (link->book != NULL)
+                return link->book->book_id;
+
+        return "";
 }
 
 /**
- * dh_link_set_flags:
- * @link: a #DhLink.
- * @flags: the new flags of the link.
+ * dh_link_compare:
+ * @a: (type DhLink): a #DhLink.
+ * @b: (type DhLink): a #DhLink.
  *
- * Sets the flags of the link.
+ * Compares the links @a and @b. This function is used to determine in which
+ * order the links should be displayed.
+ *
+ * Returns: an integer less than zero if @a should appear before @b; zero if
+ * there are no preferences; an integer greater than zero if @b should appear
+ * before @a.
  */
-void
-dh_link_set_flags (DhLink      *link,
-                   DhLinkFlags  flags)
+gint
+dh_link_compare (gconstpointer a,
+                 gconstpointer b)
 {
-        g_return_if_fail (link != NULL);
+        DhLink *la = (DhLink *) a;
+        DhLink *lb = (DhLink *) b;
+        gint flags_diff;
+        gint diff;
 
-        link->flags = flags;
+        g_return_val_if_fail (a != NULL, 0);
+        g_return_val_if_fail (b != NULL, 0);
+
+        /* Sort deprecated hits last. */
+        flags_diff = ((la->flags & DH_LINK_FLAGS_DEPRECATED) -
+                      (lb->flags & DH_LINK_FLAGS_DEPRECATED));
+        if (flags_diff != 0)
+                return flags_diff;
+
+        /* Collation-based sorting */
+        if (G_UNLIKELY (la->name_collation_key == NULL))
+                la->name_collation_key = g_utf8_collate_key (la->name, -1);
+        if (G_UNLIKELY (lb->name_collation_key == NULL))
+                lb->name_collation_key = g_utf8_collate_key (lb->name, -1);
+
+        diff = strcmp (la->name_collation_key,
+                       lb->name_collation_key);
+
+        /* For the same names, sort page links before other links. The page is
+         * more important than a symbol (typically contained in that page).
+         */
+        if (diff == 0) {
+                if (la->type == lb->type)
+                        return 0;
+
+                if (la->type == DH_LINK_TYPE_PAGE)
+                        return -1;
+
+                if (lb->type == DH_LINK_TYPE_PAGE)
+                        return 1;
+
+                return 0;
+        }
+
+        return diff;
 }
 
 /**
diff --git a/src/dh-link.h b/src/dh-link.h
index 5b20473..e5984c3 100644
--- a/src/dh-link.h
+++ b/src/dh-link.h
@@ -67,25 +67,38 @@ typedef struct _DhLink DhLink;
 #define DH_TYPE_LINK (dh_link_get_type ())
 
 GType        dh_link_get_type           (void);
+
 DhLink *     dh_link_new                (DhLinkType     type,
                                          const gchar   *base_path,
                                          const gchar   *book_id,
                                          DhLink        *book,
                                          const gchar   *name,
                                          const gchar   *relative_url);
+
 DhLink *     dh_link_ref                (DhLink        *link);
+
 void         dh_link_unref              (DhLink        *link);
-gint         dh_link_compare            (gconstpointer  a,
-                                         gconstpointer  b);
-const gchar *dh_link_get_name           (DhLink        *link);
-const gchar *dh_link_get_book_name      (DhLink        *link);
-const gchar *dh_link_get_file_name      (DhLink        *link);
-const gchar *dh_link_get_book_id        (DhLink        *link);
-gchar       *dh_link_get_uri            (DhLink        *link);
+
+DhLinkType   dh_link_get_link_type      (DhLink        *link);
+
 DhLinkFlags  dh_link_get_flags          (DhLink        *link);
+
 void         dh_link_set_flags          (DhLink        *link,
                                          DhLinkFlags    flags);
-DhLinkType   dh_link_get_link_type      (DhLink        *link);
+
+const gchar *dh_link_get_name           (DhLink        *link);
+
+const gchar *dh_link_get_file_name      (DhLink        *link);
+
+gchar *      dh_link_get_uri            (DhLink        *link);
+
+const gchar *dh_link_get_book_name      (DhLink        *link);
+
+const gchar *dh_link_get_book_id        (DhLink        *link);
+
+gint         dh_link_compare            (gconstpointer  a,
+                                         gconstpointer  b);
+
 const gchar *dh_link_type_to_string     (DhLinkType     link_type);
 
 G_END_DECLS