[devhelp] DhLink: remove page link

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

commit bdc08ef63640014c2a80231cc80a2ed4b69b90e3
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Jun 3 13:51:21 2017 +0200

    DhLink: remove page link
    
    It was broken, as the comment in dh-parser.c explained.
    
    dh_link_new() and dh_link_get_page_name() are not used in gnome-builder
    or Anjuta, so we can break the API.
    
    This commit:
    - removes the @page param of dh_link_new().
    - removes dh_link_get_page_name().
    - removes the @page field in the DhLink struct.

 docs/reference/api-breaks.xml       |   18 ++++++++++++++
 docs/reference/devhelp-sections.txt |    1 -
 src/dh-link.c                       |   43 ++++------------------------------
 src/dh-link.h                       |    4 ---
 src/dh-parser.c                     |   34 ---------------------------
 5 files changed, 23 insertions(+), 77 deletions(-)
---
diff --git a/docs/reference/api-breaks.xml b/docs/reference/api-breaks.xml
index 38baba3..b8b7666 100644
--- a/docs/reference/api-breaks.xml
+++ b/docs/reference/api-breaks.xml
@@ -105,4 +105,22 @@
       </listitem>
     </itemizedlist>
   </refsect1>
+
+  <refsect1>
+    <title>3.25.1 -> 3.25.2</title>
+    <itemizedlist>
+      <listitem>
+        <para>
+          The <code>page</code> parameter of <link linkend="dh-link-new">dh_link_new()</link>
+          has been removed because it was broken in <code>dh-parser.c</code>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <code>dh_link_get_page_name()</code> function has been removed
+          because it was broken and used nowhere.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </refsect1>
 </part>
diff --git a/docs/reference/devhelp-sections.txt b/docs/reference/devhelp-sections.txt
index 971bb29..6dc2d08 100644
--- a/docs/reference/devhelp-sections.txt
+++ b/docs/reference/devhelp-sections.txt
@@ -114,7 +114,6 @@ dh_link_unref
 dh_link_compare
 dh_link_get_name
 dh_link_get_book_name
-dh_link_get_page_name
 dh_link_get_file_name
 dh_link_get_book_id
 dh_link_get_uri
diff --git a/src/dh-link.c b/src/dh-link.c
index fa22363..2f88e7c 100644
--- a/src/dh-link.c
+++ b/src/dh-link.c
@@ -48,7 +48,6 @@ struct _DhLink {
         gchar       *relative_url;
 
         DhLink      *book;
-        DhLink      *page;
 
         guint        ref_count;
 
@@ -68,12 +67,8 @@ link_free (DhLink *link)
         g_free (link->relative_url);
         g_free (link->name_collation_key);
 
-        if (link->book) {
+        if (link->book != NULL)
                 dh_link_unref (link->book);
-        }
-        if (link->page) {
-                dh_link_unref (link->page);
-        }
 
         g_slice_free (DhLink, link);
 }
@@ -85,8 +80,6 @@ link_free (DhLink *link)
  * @book_id: (nullable): the book ID, or %NULL.
  * @name: the name of the link.
  * @book: (nullable): the book that the link is contained in, or %NULL.
- * @page: (nullable): the page that the link is contained in, or %NULL. This
- * parameter is actually broken.
  * @relative_url: the URL relative to the book @base_path. Can contain an
  * anchor.
  *
@@ -96,7 +89,7 @@ link_free (DhLink *link)
  * %DH_LINK_TYPE_BOOK.
  *
  * If @type is not a #DH_LINK_TYPE_BOOK and not a #DH_LINK_TYPE_PAGE, then the
- * @book and @page links must be provided.
+ * @book link must be provided.
  *
  * @name and @relative_url must always be provided.
  *
@@ -108,7 +101,6 @@ dh_link_new (DhLinkType   type,
              const gchar *book_id,
              const gchar *name,
              DhLink      *book,
-             DhLink      *page,
              const gchar *relative_url)
 {
         DhLink *link;
@@ -123,7 +115,6 @@ dh_link_new (DhLinkType   type,
         if (type != DH_LINK_TYPE_BOOK &&
             type != DH_LINK_TYPE_PAGE) {
                 g_return_val_if_fail (book != NULL, NULL);
-                g_return_val_if_fail (page != NULL, NULL);
         }
 
         link = g_slice_new0 (DhLink);
@@ -139,12 +130,8 @@ dh_link_new (DhLinkType   type,
         link->name = g_strdup (name);
         link->relative_url = g_strdup (relative_url);
 
-        if (book != NULL) {
+        if (book != NULL)
                 link->book = dh_link_ref (book);
-        }
-        if (page != NULL) {
-                link->page = dh_link_ref (page);
-        }
 
         return link;
 }
@@ -269,24 +256,6 @@ dh_link_get_book_name (DhLink *link)
 }
 
 /**
- * dh_link_get_page_name:
- * @link: a #DhLink.
- *
- * Returns: the name of the page that the @link is contained in.
- * Deprecated: 3.26: This function is used nowhere and is actually broken, it
- * returns the book name.
- */
-const gchar *
-dh_link_get_page_name (DhLink *link)
-{
-        if (link->page != NULL) {
-                return link->page->name;
-        }
-
-        return "";
-}
-
-/**
  * dh_link_get_file_name:
  * @link: a #DhLink.
  *
@@ -296,12 +265,10 @@ const gchar *
 dh_link_get_file_name (DhLink *link)
 {
         /* Return filename if the link is itself a page or if the link is within
-         * a page.
+         * a page (i.e. every link type except a book).
          */
-        if (link->page != NULL ||
-            link->type == DH_LINK_TYPE_PAGE) {
+        if (link->type != DH_LINK_TYPE_BOOK)
                 return link->relative_url;
-        }
 
         return "";
 }
diff --git a/src/dh-link.h b/src/dh-link.h
index a48eaa8..778959c 100644
--- a/src/dh-link.h
+++ b/src/dh-link.h
@@ -72,7 +72,6 @@ DhLink *     dh_link_new                (DhLinkType     type,
                                          const gchar   *book_id,
                                          const gchar   *name,
                                          DhLink        *book,
-                                         DhLink        *page,
                                          const gchar   *relative_url);
 DhLink *     dh_link_ref                (DhLink        *link);
 void         dh_link_unref              (DhLink        *link);
@@ -89,9 +88,6 @@ void         dh_link_set_flags          (DhLink        *link,
 DhLinkType   dh_link_get_link_type      (DhLink        *link);
 const gchar *dh_link_get_type_as_string (DhLink        *link);
 
-G_DEPRECATED
-const gchar *dh_link_get_page_name      (DhLink        *link);
-
 G_END_DECLS
 
 #endif /* DH_LINK_H */
diff --git a/src/dh-parser.c b/src/dh-parser.c
index adfb53e..e3daaed 100644
--- a/src/dh-parser.c
+++ b/src/dh-parser.c
@@ -207,7 +207,6 @@ parser_start_node_book (DhParser             *parser,
                             parser->book_name,
                             parser->book_title,
                             NULL,
-                            NULL,
                             uri);
         g_free (base);
         parser->all_links = g_list_prepend (parser->all_links, link);
@@ -270,7 +269,6 @@ parser_start_node_chapter (DhParser             *parser,
                             NULL,
                             name,
                             parser->book_node->data,
-                            NULL,
                             uri);
 
         parser->all_links = g_list_prepend (parser->all_links, link);
@@ -429,44 +427,12 @@ parser_start_node_keyword (DhParser             *parser,
         }
 
         g_assert (parser->book_node != NULL);
-        g_assert (parser->parent_node != NULL);
 
-        /* FIXME the before last parameter, the page DhLink, is broken.
-         * parser->parent_node == parser->book_node here, see the
-         * g_return_if_fail() in parser_end_node_cb().
-         *
-         * So parser->parent_node->data is actually the book DhLink.
-         *
-         * dh_link_get_page_name() is deprecated because it's used nowhere. But
-         * that function is broken, since it actually returns the book name.
-         *
-         * It's not really clear what to do. When creating a keyword DhLink, we
-         * don't know the page DhLink, but with the link attribute (the variable
-         * 'uri' below) we can remove the anchor and have the html page as a
-         * string, for example:
-         *
-         * <keyword type="function" name="dh_init ()"
-         * link="devhelp-Initialization-and-Finalization.html#dh-init"/>
-         *
-         * --> the page is: devhelp-Initialization-and-Finalization.html
-         *
-         * And with the page as a string, DhBook is able to search the DhLink
-         * for the page. Not sure that's useful though, maybe all that stuff can
-         * be removed altogether.
-         *
-         * A potential use-case to have the page name is to show in search
-         * results the page name alongside a signal or property (but ideally it
-         * should be the *class* name, not the page name, but usually a page
-         * contains only one class). But gtk-doc could directly add the class
-         * name in the name of signals and properties. See:
-         * https://bugzilla.gnome.org/show_bug.cgi?id=782546
-         */
         link = dh_link_new (link_type,
                             NULL,
                             NULL,
                             name,
                             parser->book_node->data,
-                            parser->parent_node->data, /* FIXME broken */
                             uri);
 
         g_free (name_to_free);