[devhelp] DhLink: create book link with dh_link_new_book()

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

commit b3d15e50dd5ccc19c984b993b16b5f8d22ab0fe6
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Dec 3 13:07:30 2017 +0100

    DhLink: create book link with dh_link_new_book()
    
    And simplify dh_link_new().
    
    The constructors are now simpler, they have less parameters, less
    documentation is needed. A function should do only one thing but do it
    well™.

 docs/reference/api-breaks.xml       |   14 +++++
 docs/reference/devhelp-sections.txt |    1 +
 src/dh-link.c                       |   93 ++++++++++++++++++++---------------
 src/dh-link.h                       |    7 ++-
 src/dh-parser.c                     |   14 ++----
 5 files changed, 78 insertions(+), 51 deletions(-)
---
diff --git a/docs/reference/api-breaks.xml b/docs/reference/api-breaks.xml
index 2c700dc..1c3cfe9 100644
--- a/docs/reference/api-breaks.xml
+++ b/docs/reference/api-breaks.xml
@@ -133,4 +133,18 @@
       </listitem>
     </itemizedlist>
   </refsect1>
+
+  <refsect1>
+    <title>3.26.0 -> 3.27.1</title>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <link linkend="dh-link-new">dh_link_new()</link> has been split in
+          two, with <link linkend="dh-link-new-book">dh_link_new_book()</link>
+          to create a <link linkend="DhLink">DhLink</link> of type
+          <link linkend="DH-LINK-TYPE-BOOK:CAPS">DH_LINK_TYPE_BOOK</link>.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </refsect1>
 </part>
diff --git a/docs/reference/devhelp-sections.txt b/docs/reference/devhelp-sections.txt
index 7a6ebfe..4b7203c 100644
--- a/docs/reference/devhelp-sections.txt
+++ b/docs/reference/devhelp-sections.txt
@@ -108,6 +108,7 @@ dh_keyword_model_get_type
 DhLink
 DhLinkType
 DhLinkFlags
+dh_link_new_book
 dh_link_new
 dh_link_ref
 dh_link_unref
diff --git a/src/dh-link.c b/src/dh-link.c
index 751e035..30e2808 100644
--- a/src/dh-link.c
+++ b/src/dh-link.c
@@ -73,65 +73,80 @@ link_free (DhLink *link)
         g_slice_free (DhLink, link);
 }
 
+static DhLink *
+dh_link_new_common (DhLinkType   type,
+                    const gchar *name,
+                    const gchar *relative_url)
+{
+        DhLink *link;
+
+        link = g_slice_new0 (DhLink);
+        link->ref_count = 1;
+        link->type = type;
+        link->name = g_strdup (name);
+        link->relative_url = g_strdup (relative_url);
+
+        return link;
+}
+
 /**
- * dh_link_new:
- * @type: the #DhLinkType.
- * @base_path: (nullable): the base path for the book, or %NULL.
- * @book_id: (nullable): the book ID, or %NULL.
+ * dh_link_new_book:
+ * @base_path: the base path for the book.
+ * @book_id: the book ID.
  * @name: the name of the link.
- * @book: (nullable): the book that the link is contained in, or %NULL.
  * @relative_url: the URL relative to the book @base_path. Can contain an
  * anchor.
  *
- * Creates a new #DhLink.
- *
- * @base_path and @book_id must be provided only for a link of type
- * %DH_LINK_TYPE_BOOK.
- *
- * If @type is not a #DH_LINK_TYPE_BOOK, then the @book link must be provided.
- *
- * @name and @relative_url must always be provided.
+ * Returns: a new #DhLink of type %DH_LINK_TYPE_BOOK.
+ * Since: 3.28
+ */
+DhLink *
+dh_link_new_book (const gchar *base_path,
+                  const gchar *book_id,
+                  const gchar *name,
+                  const gchar *relative_url)
+{
+        DhLink *link;
+
+        g_return_val_if_fail (base_path != NULL, NULL);
+        g_return_val_if_fail (book_id != NULL, NULL);
+        g_return_val_if_fail (name != NULL, NULL);
+        g_return_val_if_fail (relative_url != NULL, NULL);
+
+        link = dh_link_new_common (DH_LINK_TYPE_BOOK, name, relative_url);
+
+        link->base_path = g_strdup (base_path);
+        link->book_id = g_strdup (book_id);
+
+        return link;
+}
+
+/**
+ * dh_link_new:
+ * @type: the #DhLinkType. Must be different than %DH_LINK_TYPE_BOOK.
+ * @book: the book that the link is contained in.
+ * @name: the name of the link.
+ * @relative_url: the URL relative to the book @base_path. Can contain an
+ * anchor.
  *
  * Returns: a new #DhLink.
  */
 DhLink *
 dh_link_new (DhLinkType   type,
-             const gchar *base_path,
-             const gchar *book_id,
              DhLink      *book,
              const gchar *name,
              const gchar *relative_url)
 {
         DhLink *link;
 
-        if (type == DH_LINK_TYPE_BOOK) {
-                g_return_val_if_fail (base_path != NULL, NULL);
-                g_return_val_if_fail (book_id != NULL, NULL);
-                g_return_val_if_fail (book == NULL, NULL);
-        } else {
-                g_return_val_if_fail (base_path == NULL, NULL);
-                g_return_val_if_fail (book_id == NULL, NULL);
-                g_return_val_if_fail (book != NULL, NULL);
-        }
-
+        g_return_val_if_fail (type != DH_LINK_TYPE_BOOK, NULL);
+        g_return_val_if_fail (book != NULL, NULL);
         g_return_val_if_fail (name != NULL, NULL);
         g_return_val_if_fail (relative_url != NULL, NULL);
 
-        link = g_slice_new0 (DhLink);
-
-        link->ref_count = 1;
-        link->type = type;
+        link = dh_link_new_common (type, name, relative_url);
 
-        if (type == DH_LINK_TYPE_BOOK) {
-                link->base_path = g_strdup (base_path);
-                link->book_id = g_strdup (book_id);
-        }
-
-        if (book != NULL)
-                link->book = dh_link_ref (book);
-
-        link->name = g_strdup (name);
-        link->relative_url = g_strdup (relative_url);
+        link->book = dh_link_ref (book);
 
         return link;
 }
diff --git a/src/dh-link.h b/src/dh-link.h
index e5984c3..dddb83d 100644
--- a/src/dh-link.h
+++ b/src/dh-link.h
@@ -68,9 +68,12 @@ typedef struct _DhLink DhLink;
 
 GType        dh_link_get_type           (void);
 
-DhLink *     dh_link_new                (DhLinkType     type,
-                                         const gchar   *base_path,
+DhLink *     dh_link_new_book           (const gchar   *base_path,
                                          const gchar   *book_id,
+                                         const gchar   *name,
+                                         const gchar   *relative_url);
+
+DhLink *     dh_link_new                (DhLinkType     type,
                                          DhLink        *book,
                                          const gchar   *name,
                                          const gchar   *relative_url);
diff --git a/src/dh-parser.c b/src/dh-parser.c
index 9aa8eeb..5e1d217 100644
--- a/src/dh-parser.c
+++ b/src/dh-parser.c
@@ -201,12 +201,10 @@ parser_start_node_book (DhParser             *parser,
                 g_object_unref (directory);
         }
 
-        link = dh_link_new (DH_LINK_TYPE_BOOK,
-                            base,
-                            parser->book_name,
-                            NULL,
-                            parser->book_title,
-                            uri);
+        link = dh_link_new_book (base,
+                                 parser->book_name,
+                                 parser->book_title,
+                                 uri);
         g_free (base);
         parser->all_links = g_list_prepend (parser->all_links, link);
 
@@ -264,8 +262,6 @@ parser_start_node_chapter (DhParser             *parser,
         g_assert (parser->book_node != NULL);
 
         link = dh_link_new (DH_LINK_TYPE_PAGE,
-                            NULL,
-                            NULL,
                             parser->book_node->data,
                             name,
                             uri);
@@ -428,8 +424,6 @@ parser_start_node_keyword (DhParser             *parser,
         g_assert (parser->book_node != NULL);
 
         link = dh_link_new (link_type,
-                            NULL,
-                            NULL,
                             parser->book_node->data,
                             name,
                             uri);