add support for gtkdoc style links in docs

Short explanation of how it works (needs to go into some docs)

 - com.example.Foo() links to the Foo() method on com.example
 - #com.example::Changed links to the Changed signal on com.example
 - #com.example:SomeProperty links to the SomeProperty property on com.example
 - #com.example links to the com.example interface
 - %com.example.Error.Failed links to the com.example.Error.Failed error
 - #com.example.Error links to the whole error enumeration com.example.*
 - %Car.Volvo links to the Volvo constant in the Car enumeration (ditto flags)
 - %Car links to the Car enumeration (ditto flags)

So, yeah, pretty much like gtk-doc.

Note that for generating gtk-doc comments, these things are translated
into the namespace used, e.g. com.example.Foo() will be translated to
my_namespace_example_foo if MyNamspaceExample is the GObject type for
the com.example interface. Ditto for signals, properties, errors and
enumerations.

10 files changed, 778 insertions, 349 deletions

diff --git a/src/eggdbus/docbook.c b/src/eggdbus/docbook.c
index f20bd4b..61934cb 100644
--- a/src/eggdbus/docbook.c
+++ b/src/eggdbus/docbook.c
@@ -324,7 +324,7 @@ docbook_print_method_prototype (const EggDBusInterfaceInfo          *interface,
 
   if (use_hyperlink)
     {
-      g_print ("<link linkend=\"%s.%s\">%s</link>%*s(",
+      g_print ("<link linkend=\"eggdbus-method-%s.%s\">%s</link>%*s(",
                interface->name,
                method->name,
                method->name,
@@ -380,7 +380,7 @@ docbook_print_signal_prototype (const EggDBusInterfaceInfo          *interface,
 
   if (use_hyperlink)
     {
-      g_print ("<link linkend=\"%s::%s\">%s</link>%*s(",
+      g_print ("<link linkend=\"eggdbus-signal-%s::%s\">%s</link>%*s(",
                interface->name,
                signal->name,
                signal->name,
@@ -422,7 +422,7 @@ docbook_print_property_prototype (const EggDBusInterfaceInfo          *interface
 
   if (use_hyperlink)
     {
-      g_print ("<link linkend=\"%s:%s\">%s</link>%*s    ",
+      g_print ("<link linkend=\"eggdbus-property-%s:%s\">%s</link>%*s    ",
                interface->name,
                property->name,
                property->name,
@@ -467,7 +467,7 @@ docbook_print_arg_in_list (const gchar                   *prefix,
   gchar *arg_doc_string;
   gchar *arg_type_link;
 
-  arg_doc_string = get_doc_string (arg->annotations, "Argument");
+  arg_doc_string = get_doc (arg->annotations, DOC_TYPE_DOCBOOK);
 
   docbook_get_typename_for_signature (arg->signature, NULL, &arg_type_link);
 
@@ -529,19 +529,19 @@ interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
 
   ret = FALSE;
 
-  interface_summary_doc_string = get_summary_doc_string (interface->annotations, "Interface");
-  interface_doc_string = get_doc_string (interface->annotations, "Interface");
+  interface_summary_doc_string = get_doc_summary (interface->annotations, DOC_TYPE_DOCBOOK);
+  interface_doc_string = get_doc (interface->annotations, DOC_TYPE_DOCBOOK);
 
   g_print ("<?xml version=\"1.0\"?>\n"
            "<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2 //EN\"\n"
            "\"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">\n");
 
-  g_print ("<refentry id=\"%s\">\n", interface->name);
+  g_print ("<refentry id=\"eggdbus-interface-%s\">\n", interface->name);
   g_print ("  <refmeta>\n");
-  g_print ("    <refentrytitle role=\"top_of_page\">%s</refentrytitle>\n", interface->name);
+  g_print ("    <refentrytitle role=\"top_of_page\">%s Interface</refentrytitle>\n", interface->name);
   g_print ("  </refmeta>\n");
   g_print ("  <refnamediv>\n");
-  g_print ("    <refname>%s</refname>\n", interface->name);
+  g_print ("    <refname>%s Interface</refname>\n", interface->name);
   g_print ("    <refpurpose>%s</refpurpose>\n", interface_summary_doc_string);
   g_print ("  </refnamediv>\n");
 
@@ -671,8 +671,8 @@ interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
 
           arg_max_len = docbook_get_max_arg_len_for_method (method);
 
-          g_print ("    <refsect2>\n");
-          g_print ("      <title><anchor role=\"function\" id=\"%s.%s\"/>%s ()</title>\n",
+          g_print ("    <refsect2 role=\"function\" id=\"eggdbus-method-%s.%s\">\n"
+                   "      <title>%s ()</title>\n",
                    interface->name,
                    method->name,
                    method->name);
@@ -686,7 +686,7 @@ interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
 
           g_print ("    </programlisting>\n");
           g_print ("    <para>\n");
-          doc_string = get_doc_string (method->annotations, "Method");
+          doc_string = get_doc (method->annotations, DOC_TYPE_DOCBOOK);
           g_print ("%s\n", doc_string);
           g_free (doc_string);
           g_print ("    </para>\n");
@@ -720,8 +720,8 @@ interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
 
           arg_max_len = docbook_get_max_arg_len_for_signal (signal);
 
-          g_print ("    <refsect2>\n");
-          g_print ("      <title><anchor role=\"function\" id=\"%s::%s\"/>The %s () signal</title>\n",
+          g_print ("    <refsect2 role=\"signal\" id=\"eggdbus-signal-%s::%s\">\n"
+                   "      <title>The \"%s\" signal</title>\n",
                    interface->name,
                    signal->name,
                    signal->name);
@@ -735,7 +735,7 @@ interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
 
           g_print ("    </programlisting>\n");
           g_print ("    <para>\n");
-          doc_string = get_doc_string (signal->annotations, "Signal");
+          doc_string = get_doc (signal->annotations, DOC_TYPE_DOCBOOK);
           g_print ("%s\n", doc_string);
           g_free (doc_string);
           g_print ("    </para>\n");
@@ -766,8 +766,8 @@ interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
 
           property_name_len = strlen (property->name);
 
-          g_print ("    <refsect2>\n");
-          g_print ("      <title><anchor role=\"function\" id=\"%s:%s\"/>The \"%s\" property</title>\n",
+          g_print ("    <refsect2 role=\"property\" id=\"eggdbus-property-%s:%s\">\n"
+                   "      <title>The \"%s\" property</title>\n",
                    interface->name,
                    property->name,
                    property->name);
@@ -780,7 +780,7 @@ interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
 
           g_print ("    </programlisting>\n");
           g_print ("    <para>\n");
-          doc_string = get_doc_string (property->annotations, "Property");
+          doc_string = get_doc (property->annotations, DOC_TYPE_DOCBOOK);
           g_print ("%s\n", doc_string);
           g_free (doc_string);
           g_print ("    </para>\n");
@@ -841,6 +841,7 @@ enum_generate_docbook (EnumData  *enum_data,
   guint max_len;
   guint m;
   gboolean has_none_elem;
+  gchar *title;
 
   ret = FALSE;
   has_none_elem = TRUE;
@@ -849,14 +850,17 @@ enum_generate_docbook (EnumData  *enum_data,
     {
     case ENUM_DATA_TYPE_ERROR_DOMAIN:
       type_string = "Error Domain";
+      title = g_strdup_printf ("%s* Error Domain", enum_data->maximal_dbus_prefix);
       break;
 
     case ENUM_DATA_TYPE_FLAGS:
       type_string = "Flags";
+      title = g_strdup_printf ("%s Flag Enumeration", enum_data->name);
       break;
 
     case ENUM_DATA_TYPE_ENUM:
       type_string = "Enumeration";
+      title = g_strdup_printf ("%s Enumeration", enum_data->name);
       break;
 
     default:
@@ -864,34 +868,35 @@ enum_generate_docbook (EnumData  *enum_data,
       break;
     }
 
-  enum_summary_doc_string = get_summary_doc_string (enum_data->annotations, type_string);
-  enum_doc_string = get_doc_string (enum_data->annotations, type_string);
+  enum_summary_doc_string = get_doc_summary (enum_data->annotations, DOC_TYPE_DOCBOOK);
+  enum_doc_string = get_doc (enum_data->annotations, DOC_TYPE_DOCBOOK);
 
   g_print ("<?xml version=\"1.0\"?>\n"
            "<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2 //EN\"\n"
            "\"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">\n");
 
-  g_print ("<refentry id=\"enum-%s\">\n", enum_data->name);
+  g_print ("<refentry id=\"eggdbus-enummain-%s\">\n", enum_data->name);
   g_print ("  <refmeta>\n");
-  g_print ("    <refentrytitle role=\"top_of_page\">%s</refentrytitle>\n", enum_data->name);
+  g_print ("    <refentrytitle role=\"top_of_page\">%s</refentrytitle>\n", title);
   g_print ("  </refmeta>\n");
   g_print ("  <refnamediv>\n");
-  g_print ("    <refname>%s</refname>\n", enum_data->name);
+  g_print ("    <refname>%s</refname>\n", title);
   g_print ("    <refpurpose>%s</refpurpose>\n", enum_summary_doc_string);
   g_print ("  </refnamediv>\n");
 
   g_print ("  <refsect1>\n");
 
-  g_print ("    <refsect2>\n");
   if (enum_data->type == ENUM_DATA_TYPE_ERROR_DOMAIN)
     {
-      g_print ("      <title><anchor role=\"enum\" id=\"%s\"/>The %s* Error Domain</title>\n",
+      g_print ("    <refsect2 role=\"enum\" id=\"eggdbus-errordomain-%s\">"
+               "      <title>The %s* Error Domain</title>\n",
                enum_data->maximal_dbus_prefix,
                enum_data->maximal_dbus_prefix);
     }
   else
     {
-      g_print ("      <title><anchor role=\"enum\" id=\"%s\"/>The %s %s</title>\n",
+      g_print ("    <refsect2 role=\"enum\" id=\"eggdbus-enum-%s\">\n"
+               "      <title>The %s %s</title>\n",
                enum_data->name,
                enum_data->name,
                type_string);
@@ -997,7 +1002,7 @@ enum_generate_docbook (EnumData  *enum_data,
     {
       if (!has_none_elem)
         {
-          g_print ("  <varlistentry id=\"constant-%s.None\" role=\"constant\">\n", enum_data->name);
+          g_print ("  <varlistentry id=\"eggdbus-constant-%s.None\" role=\"constant\">\n", enum_data->name);
           g_print ("    <term><literal>None</literal></term>\n");
           g_print ("    <listitem>\n");
           g_print ("      <para>\n");
@@ -1013,20 +1018,20 @@ enum_generate_docbook (EnumData  *enum_data,
       EnumElemData *elem = enum_data->elements[n];
       gchar *enum_doc_string;
 
-      enum_doc_string = get_doc_string (elem->annotations, "Enum");
+      enum_doc_string = get_doc (elem->annotations, DOC_TYPE_DOCBOOK);
 
       switch (enum_data->type)
         {
         case ENUM_DATA_TYPE_ERROR_DOMAIN:
-          g_print ("  <varlistentry id=\"constant-%s\" role=\"constant\">\n", elem->name);
+          g_print ("  <varlistentry id=\"eggdbus-constant-%s.%s\" role=\"constant\">\n", enum_data->name, elem->name);
           break;
 
         case ENUM_DATA_TYPE_FLAGS:
-          g_print ("  <varlistentry id=\"constant-%s.%s\" role=\"constant\">\n", enum_data->name, elem->name);
+          g_print ("  <varlistentry id=\"eggdbus-constant-%s.%s\" role=\"constant\">\n", enum_data->name, elem->name);
           break;
 
         case ENUM_DATA_TYPE_ENUM:
-          g_print ("  <varlistentry id=\"constant-%s.%s\" role=\"constant\">\n", enum_data->name, elem->name);
+          g_print ("  <varlistentry id=\"eggdbus-constant-%s.%s\" role=\"constant\">\n", enum_data->name, elem->name);
           break;
         }
       g_print ("    <term><literal>%s</literal></term>\n", elem->name);
@@ -1052,6 +1057,7 @@ enum_generate_docbook (EnumData  *enum_data,
 
   g_free (enum_doc_string);
   g_free (enum_summary_doc_string);
+  g_free (title);
 
   return ret;
 }
@@ -1072,26 +1078,26 @@ struct_generate_docbook (StructData  *struct_data,
   ret = FALSE;
   has_none_elem = TRUE;
 
-  struct_summary_doc_string = get_summary_doc_string (struct_data->annotations, "Structure");
-  struct_doc_string = get_doc_string (struct_data->annotations, "Structure");
+  struct_summary_doc_string = get_doc_summary (struct_data->annotations, DOC_TYPE_DOCBOOK);
+  struct_doc_string = get_doc (struct_data->annotations, DOC_TYPE_DOCBOOK);
 
   g_print ("<?xml version=\"1.0\"?>\n"
            "<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2 //EN\"\n"
            "\"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">\n");
 
-  g_print ("<refentry id=\"struct-%s\">\n", struct_data->name);
+  g_print ("<refentry id=\"eggdbus-structmain-%s\">\n", struct_data->name);
   g_print ("  <refmeta>\n");
-  g_print ("    <refentrytitle role=\"top_of_page\">%s</refentrytitle>\n", struct_data->name);
+  g_print ("    <refentrytitle role=\"top_of_page\">%s Structure</refentrytitle>\n", struct_data->name);
   g_print ("  </refmeta>\n");
   g_print ("  <refnamediv>\n");
-  g_print ("    <refname>%s</refname>\n", struct_data->name);
+  g_print ("    <refname>%s Structure</refname>\n", struct_data->name);
   g_print ("    <refpurpose>%s</refpurpose>\n", struct_summary_doc_string);
   g_print ("  </refnamediv>\n");
 
   g_print ("  <refsect1>\n");
 
-  g_print ("    <refsect2>\n");
-  g_print ("      <title><anchor role=\"struct\" id=\"%s\"/>The %s Structure</title>\n",
+  g_print ("    <refsect2 role=\"struct\" id=\"eggdbus-struct-%s\">\n"
+           "      <title>The %s Structure</title>\n",
            struct_data->name,
            struct_data->name);
   g_print ("        <para>\n");
@@ -1147,7 +1153,7 @@ struct_generate_docbook (StructData  *struct_data,
       gchar *struct_doc_string;
       gchar *type_name_link;
 
-      struct_doc_string = get_doc_string (elem->annotations, "Member");
+      struct_doc_string = get_doc (elem->annotations, DOC_TYPE_DOCBOOK);
       docbook_get_typename_for_signature (elem->signature, NULL, &type_name_link);
 
       g_print ("  <varlistentry>\n");
diff --git a/src/eggdbus/eggdbusbindingtool.c b/src/eggdbus/eggdbusbindingtool.c
index 6b60691..046eeb1 100644
--- a/src/eggdbus/eggdbusbindingtool.c
+++ b/src/eggdbus/eggdbusbindingtool.c
@@ -78,36 +78,414 @@ static GSList *marshallers_to_generate = NULL;
 
 /* ---------------------------------------------------------------------------------------------------- */
 
-gchar *
-get_summary_doc_string (const EggDBusInterfaceAnnotationInfo *annotations,
-                        const gchar                          *entity_type)
+static GRegex *link_regex = NULL;
+static GHashTable *gtkdoc_links = NULL;
+static GHashTable *docbook_links = NULL;
+
+static gboolean
+create_link_regexs (GError **error)
 {
-  gchar *doc_string;
+  gboolean ret;
+  GSList *l;
+  guint n;
+  gchar *id;
+  gchar *gtkdoc_val;
+  gchar *docbook_val;
+  GHashTableIter hash_iter;
+  const gchar *iface_name;
+  EggDBusInterfaceInfo *interface;
+  char *name_space_uscore;
+  char *name_space_uscore_upper;
 
-  doc_string = g_strdup (egg_dbus_interface_annotation_info_lookup (annotations,
-                                                                    "org.gtk.EggDBus.DocString.Summary"));
+  name_space_uscore = egg_dbus_utils_camel_case_to_uscore (name_space);
+  name_space_uscore_upper = g_ascii_strup (name_space_uscore, -1);
 
-  if (doc_string == NULL)
-    doc_string = g_strdup_printf ("FIXME: %s is not documented (no summary).", entity_type);
+  ret = FALSE;
 
-  return doc_string;
+  link_regex = g_regex_new ("("
+                             "([\\w.]+)\\s*\\(\\)"       /* method_call() */
+                            ")|("
+                             "\\@(\\w+((\\.|->)\\w+)*)"  /* @param */
+                            ")|("
+                             "\\%(-?[\\w.]+)"            /* %constant */
+                            ")|("
+                             "#([\\w\\.-:]+)"            /* #symbol */
+                            ")",
+                            G_REGEX_OPTIMIZE,
+                            0,
+                            error);
+  if (link_regex == NULL)
+    goto out;
+
+  gtkdoc_links = g_hash_table_new_full (g_str_hash,
+                                        g_str_equal,
+                                        g_free,
+                                        g_free);
+
+  docbook_links = g_hash_table_new_full (g_str_hash,
+                                         g_str_equal,
+                                         NULL, //g_free,
+                                         g_free);
+
+  /* first, some widely-used constants */
+  id = g_strdup ("%TRUE");
+  gtkdoc_val = g_strdup ("%TRUE");
+  docbook_val = g_strdup ("<literal>TRUE</literal>");
+  g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+  g_hash_table_insert (docbook_links, id, docbook_val);
+  id = g_strdup ("%TRUE.");
+  gtkdoc_val = g_strdup ("%TRUE.");
+  docbook_val = g_strdup ("<literal>TRUE</literal>.");
+  g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+  g_hash_table_insert (docbook_links, id, docbook_val);
+
+  id = g_strdup ("%FALSE");
+  gtkdoc_val = g_strdup ("%FALSE");
+  docbook_val = g_strdup ("<literal>FALSE</literal>");
+  g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+  g_hash_table_insert (docbook_links, id, docbook_val);
+  id = g_strdup ("%FALSE.");
+  gtkdoc_val = g_strdup ("%FALSE.");
+  docbook_val = g_strdup ("<literal>FALSE</literal>.");
+  g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+  g_hash_table_insert (docbook_links, id, docbook_val);
+
+  /* add links for all enums */
+  for (l = enum_data_list; l != NULL; l = l->next)
+    {
+      EnumData *enum_data = l->data;
+
+      /* make links to the enumeration itself */
+      if (enum_data->type == ENUM_DATA_TYPE_ERROR_DOMAIN)
+        {
+          id = g_strdup_printf ("#%s", enum_data->maximal_dbus_prefix);
+          id[strlen(id) - 1] = '\0';
+          docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-enummain-%s\">%s* Error Domain</link>",
+                                         enum_data->name,
+                                         enum_data->maximal_dbus_prefix);
+        }
+      else
+        {
+          id = g_strdup_printf ("#%s", enum_data->name);
+          docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-enummain-%s\">%s</link>.",
+                                         enum_data->name,
+                                         enum_data->name);
+        }
+      gtkdoc_val = g_strdup_printf ("#%s%s", name_space, enum_data->name);
+      docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-enummain-%s\">%s</link>",
+                                     enum_data->name,
+                                     enum_data->name);
+      g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+      g_hash_table_insert (docbook_links, id, docbook_val);
+
+      if (enum_data->type == ENUM_DATA_TYPE_ERROR_DOMAIN)
+        {
+          id = g_strdup_printf ("#%s.", enum_data->maximal_dbus_prefix);
+          id[strlen(id) - 1] = '\0';
+          docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-enummain-%s\">%s* Error Domain</link>.",
+                                         enum_data->name,
+                                         enum_data->maximal_dbus_prefix);
+        }
+      else
+        {
+          id = g_strdup_printf ("#%s.", enum_data->name);
+          docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-enummain-%s\">%s</link>.",
+                                         enum_data->name,
+                                         enum_data->name);
+        }
+      gtkdoc_val = g_strdup_printf ("#%s%s.", name_space, enum_data->name);
+      g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+      g_hash_table_insert (docbook_links, id, docbook_val);
+
+      for (n = 0; n < enum_data->num_elements; n++)
+        {
+          EnumElemData *elem = enum_data->elements[n];
+
+          if (enum_data->type == ENUM_DATA_TYPE_ERROR_DOMAIN)
+            id = g_strdup_printf ("%%%s", elem->name);
+          else
+            id = g_strdup_printf ("%%%s.%s", enum_data->name, elem->name);
+          gtkdoc_val = g_strdup_printf ("%%%s_%s_%s",
+                                        name_space_uscore_upper,
+                                        enum_data->name_uscore_upper,
+                                        elem->g_name_uscore_upper);
+          if (enum_data->type == ENUM_DATA_TYPE_ERROR_DOMAIN)
+            docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-constant-%s.%s\">%s</link>",
+                                           enum_data->name, elem->name,
+                                           elem->name);
+          else
+            docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-constant-%s.%s\">%s.%s</link>",
+                                           enum_data->name, elem->name,
+                                           enum_data->name, elem->name);
+          g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+          g_hash_table_insert (docbook_links, id, docbook_val);
+
+          if (enum_data->type == ENUM_DATA_TYPE_ERROR_DOMAIN)
+            id = g_strdup_printf ("%%%s.", elem->name);
+          else
+            id = g_strdup_printf ("%%%s.%s.", enum_data->name, elem->name);
+          gtkdoc_val = g_strdup_printf ("%%%s_%s_%s.",
+                                        name_space_uscore_upper,
+                                        enum_data->name_uscore_upper,
+                                        elem->g_name_uscore_upper);
+          if (enum_data->type == ENUM_DATA_TYPE_ERROR_DOMAIN)
+            docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-constant-%s.%s\">%s</link>.",
+                                           enum_data->name, elem->name,
+                                           elem->name);
+          else
+            docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-constant-%s.%s\">%s.%s</link>.",
+                                           enum_data->name, elem->name,
+                                           enum_data->name, elem->name);
+          g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+          g_hash_table_insert (docbook_links, id, docbook_val);
+        }
+    }
+
+  /* add links for all structs */
+  for (l = struct_data_list; l != NULL; l = l->next)
+    {
+      StructData *struct_data = l->data;
+
+      /* only make links for the struct itself, not any of it's members (TODO: should we?) */
+      id = g_strdup_printf ("#%s", struct_data->name);
+      gtkdoc_val = g_strdup_printf ("#%s%s", name_space, struct_data->name);
+      docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-struct-%s\">%s</link>",
+                                     struct_data->name,
+                                     struct_data->name);
+      g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+      g_hash_table_insert (docbook_links, id, docbook_val);
+
+      id = g_strdup_printf ("#%s.", struct_data->name);
+      gtkdoc_val = g_strdup_printf ("#%s%s.", name_space, struct_data->name);
+      docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-struct-%s\">%s</link>.",
+                                     struct_data->name,
+                                     struct_data->name);
+      g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+      g_hash_table_insert (docbook_links, id, docbook_val);
+
+    }
+
+  /* add links for all interfaces (and methods, signals, properties) */
+  g_hash_table_iter_init (&hash_iter, all_dbus_interfaces);
+  while (g_hash_table_iter_next (&hash_iter, (gpointer) &iface_name, (gpointer) &interface))
+    {
+      gchar *iface_uscore;
+
+      iface_uscore = egg_dbus_utils_camel_case_to_uscore (iface_name);
+
+      /* make links to the interface itself */
+      id = g_strdup_printf ("#%s", interface->name);
+      gtkdoc_val = g_strdup_printf ("#%s%s", name_space, iface_name);
+      docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-interface-%s\">%s</link>",
+                                     interface->name,
+                                     interface->name);
+      g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+      g_hash_table_insert (docbook_links, id, docbook_val);
+
+      id = g_strdup_printf ("#%s.", interface->name);
+      gtkdoc_val = g_strdup_printf ("#%s%s.", name_space, iface_name);
+      docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-interface-%s\">%s</link>.",
+                                     interface->name,
+                                     interface->name);
+      g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+      g_hash_table_insert (docbook_links, id, docbook_val);
+
+      /* foreach method */
+      for (n = 0; n < interface->num_methods; n++)
+        {
+          const EggDBusInterfaceMethodInfo *method = interface->methods + n;
+          gchar *method_uscore;
+
+          method_uscore = egg_dbus_utils_camel_case_to_uscore (method->name);
+
+          id = g_strdup_printf ("%s.%s()", interface->name, method->name);
+          gtkdoc_val = g_strdup_printf ("%s_%s_%s()",
+                                        name_space_uscore,
+                                        iface_uscore,
+                                        method_uscore);
+          docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-method-%s.%s\">%s()</link>",
+                                         interface->name, method->name,
+                                         method->name);
+          g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+          g_hash_table_insert (docbook_links, id, docbook_val);
+
+          g_free (method_uscore);
+        }
+
+      /* foreach signal */
+      for (n = 0; n < interface->num_signals; n++)
+        {
+          const EggDBusInterfaceSignalInfo *signal = interface->signals + n;
+
+          id = g_strdup_printf ("#%s::%s", interface->name, signal->name);
+          gtkdoc_val = g_strdup_printf ("#%s%s::%s", name_space, iface_name, signal->g_name);
+          docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-signal-%s::%s\"><type>\"%s\"</type></link>",
+                                         interface->name, signal->name,
+                                         signal->name);
+          g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+          g_hash_table_insert (docbook_links, id, docbook_val);
+
+          id = g_strdup_printf ("#%s::%s.", interface->name, signal->name);
+          gtkdoc_val = g_strdup_printf ("#%s%s::%s.", name_space, iface_name, signal->g_name);
+          docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-signal-%s::%s\"><type>\"%s\"</type></link>.",
+                                         interface->name, signal->name,
+                                         signal->name);
+          g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+          g_hash_table_insert (docbook_links, id, docbook_val);
+        }
+
+      /* foreach property */
+      for (n = 0; n < interface->num_properties; n++)
+        {
+          const EggDBusInterfacePropertyInfo *property = interface->properties + n;
+
+          id = g_strdup_printf ("#%s:%s", interface->name, property->name);
+          gtkdoc_val = g_strdup_printf ("#%s%s:%s", name_space, iface_name, property->g_name);
+          docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-property-%s:%s\"><type>\"%s\"</type></link>",
+                                         interface->name, property->name,
+                                         property->name);
+          g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+          g_hash_table_insert (docbook_links, id, docbook_val);
+
+          id = g_strdup_printf ("#%s:%s.", interface->name, property->name);
+          gtkdoc_val = g_strdup_printf ("#%s%s:%s.", name_space, iface_name, property->g_name);
+          docbook_val = g_strdup_printf ("<link linkend=\"eggdbus-property-%s:%s\"><type>\"%s\"</type></link>.",
+                                         interface->name, property->name,
+                                         property->name);
+          g_hash_table_insert (gtkdoc_links, id, gtkdoc_val);
+          g_hash_table_insert (docbook_links, id, docbook_val);
+        }
+
+      g_free (iface_uscore);
+    }
+
+  ret = TRUE;
+
+ out:
+  g_free (name_space_uscore);
+  g_free (name_space_uscore_upper);
+  return ret;
 }
 
-gchar *
-get_doc_string (const EggDBusInterfaceAnnotationInfo *annotations,
-                const gchar                          *entity_type)
+static void
+free_link_regexs (void)
+{
+  if (gtkdoc_links != NULL)
+    g_hash_table_unref (gtkdoc_links);
+
+  if (docbook_links != NULL)
+    g_hash_table_unref (docbook_links);
+
+  if (link_regex != NULL)
+    g_regex_unref (link_regex);
+}
+
+/* ---------------------------------------------------------------------------------------------------- */
+
+static gboolean
+doc_replace_cb (const GMatchInfo *match_info,
+                GString          *result,
+                gpointer          user_data)
 {
+  DocType type;
+  gchar *match;
+  gchar *val;
+
+  type = GPOINTER_TO_INT (user_data);
+
+  match = g_match_info_fetch (match_info, 0);
+
+  val = NULL;
+  switch (type)
+    {
+    case DOC_TYPE_GTKDOC:
+      if (match[0] == '@')
+        val = g_strdup (match);
+      else
+        val = g_strdup (g_hash_table_lookup (gtkdoc_links, match));
+      break;
+
+    case DOC_TYPE_DOCBOOK:
+      if (match[0] == '@')
+        val = g_strdup_printf ("<parameter>%s</parameter>", match + 1);
+      else
+        val = g_strdup (g_hash_table_lookup (docbook_links, match));
+      break;
+    }
+
+  if (val != NULL)
+    {
+      g_string_append (result, val);
+      g_free (val);
+    }
+  else
+    {
+      g_string_append (result, match);
+      g_printerr ("Warning: unable to resolve '%s'\n", match);
+    }
+
+  g_free (match);
+
+  return FALSE;
+}
+
+static gchar *
+get_doc_from_key (const EggDBusInterfaceAnnotationInfo *annotations,
+                  const gchar                          *key,
+                  DocType                               type)
+{
+  const gchar *s;
   gchar *doc_string;
+  GError *error;
+
+  s = egg_dbus_interface_annotation_info_lookup (annotations, key);
+
+  if (s == NULL)
+    {
+      doc_string = g_strdup_printf ("FIXME: not documented.");
+      goto out;
+    }
 
-  doc_string = g_strdup (egg_dbus_interface_annotation_info_lookup (annotations,
-                                                                    "org.gtk.EggDBus.DocString"));
+  if (link_regex == NULL)
+    {
+      doc_string = g_strdup (s);
+      goto out;
+    }
 
+  error = NULL;
+  doc_string = g_regex_replace_eval (link_regex,
+                                     s,
+                                     -1,
+                                     0,
+                                     0, /* GRegexMatchFlags */
+                                     doc_replace_cb,
+                                     GINT_TO_POINTER (type),
+                                     &error);
   if (doc_string == NULL)
-    doc_string = g_strdup_printf ("FIXME: %s is not documented.", entity_type);
+    {
+      g_warning ("Error replacing links: %s", error->message);
+      g_error_free (error);
+      s = g_strdup (s);
+    }
 
+ out:
   return doc_string;
 }
 
+gchar *
+get_doc (const EggDBusInterfaceAnnotationInfo *annotations,
+         DocType                               type)
+{
+  return get_doc_from_key (annotations, "org.gtk.EggDBus.DocString", type);
+}
+
+gchar *
+get_doc_summary (const EggDBusInterfaceAnnotationInfo *annotations,
+                 DocType                               type)
+{
+  return get_doc_from_key (annotations, "org.gtk.EggDBus.DocString.Summary", type);
+}
+
 /* ---------------------------------------------------------------------------------------------------- */
 
 static StructData *
@@ -1089,16 +1467,42 @@ generate_marshallers (GError **error)
 /* ---------------------------------------------------------------------------------------------------- */
 
 static gboolean
-generate_enums (GSList   *nodes,
-                GError **error)
+parse_interfaces_enums_and_structs (GSList   *nodes,
+                                    GError **error)
 {
   guint n;
+  guint m;
+  gchar *name_space_hyphen;
   gboolean ret;
   GSList *l;
   EnumData *enum_data;
 
   ret = FALSE;
   enum_data = NULL;
+  name_space_hyphen = egg_dbus_utils_camel_case_to_hyphen (name_space);
+
+  /* look for org.gtk.EggDBus.DeclareStruct annotations for top-nodes
+   */
+  for (l = nodes; l != NULL; l = l->next)
+    {
+      EggDBusInterfaceNodeInfo *node = l->data;
+
+      for (n = 0; node->annotations != NULL && node->annotations[n].key != NULL; n++)
+        {
+          const EggDBusInterfaceAnnotationInfo *annotation = node->annotations + n;
+
+          if (strcmp (annotation->key, "org.gtk.EggDBus.DeclareStruct") == 0)
+            {
+              StructData *struct_data;
+
+              struct_data = struct_data_new_from_annotation (annotation, error);
+              if (struct_data == NULL)
+                goto out;
+
+              struct_data_list = g_slist_append (struct_data_list, struct_data);
+            }
+        }
+    }
 
   /* look for annotations
    *
@@ -1139,134 +1543,195 @@ generate_enums (GSList   *nodes,
 
           if (enum_data != NULL)
             {
-              gchar *h_file_name;
-              gchar *c_file_name;
-              gchar *docbook_file_name;
+              enum_data_list = g_slist_append (enum_data_list, enum_data);
+              enum_data = NULL;
+            }
 
-              /* now generate Docbook, H and C files for enum_data */
+        } /* for all annotations for node */
 
-              /* generate docbook file */
-              docbook_file_name = g_strdup_printf ("docbook-enum-%s.xml", enum_data->name);
-              file_print_func_begin (docbook_file_name);
-              if (!enum_generate_docbook (enum_data, error))
-                {
-                  g_free (docbook_file_name);
-                  file_print_func_end (FALSE, NULL);
-                  goto out;
-                }
-              if (!file_print_func_end (TRUE, error))
-                {
-                  g_free (docbook_file_name);
-                  goto out;
-                }
-              g_printerr ("Wrote %s\n", docbook_file_name);
-              generated_files = g_slist_prepend (generated_files, g_strdup (docbook_file_name));
-              g_free (docbook_file_name);
+    } /* for all nodes */
 
-              /* generate header file */
-              h_file_name = compute_file_name (name_space, enum_data->name, ".h");
-              file_print_func_begin (h_file_name);
 
-              if (!enum_generate_h_file (enum_data,
-                                         name_space,
-                                         h_file_name,
-                                         enum_data->name,
-                                         error))
-                {
-                  g_free (h_file_name);
-                  file_print_func_end (FALSE, NULL);
-                  goto out;
-                }
-              if (!file_print_func_end (TRUE, error))
-                {
-                  g_free (h_file_name);
-                  goto out;
-                }
-              g_printerr ("Wrote %s\n", h_file_name);
-              generated_files = g_slist_prepend (generated_files, g_strdup (h_file_name));
+  for (l = nodes; l != NULL; l = l->next)
+    {
+      const EggDBusInterfaceNodeInfo *node = l->data;
 
-              /* generate c file */
-              c_file_name = compute_file_name (name_space, enum_data->name, ".c");
-              file_print_func_begin (c_file_name);
+#if 0
+      GString *s;
+      s = g_string_new (NULL);
+      egg_dbus_interface_node_info_to_xml (node, 2, s);
+      g_printerr ("node:\n%s", s->str);
+      g_string_free (s, TRUE);
+#endif
 
-              if (!enum_generate_c_file (enum_data,
-                                         name_space,
-                                         c_file_name,
-                                         h_file_name,
-                                         enum_data->name,
-                                         error))
+      for (n = 0; n < node->num_interfaces; n++)
+        {
+          const EggDBusInterfaceInfo *interface = node->interfaces + n;
+          gchar *iface_name;
+          gchar *iface_name_hyphen;
+
+          iface_name = g_strdup (egg_dbus_interface_annotation_info_lookup (interface->annotations,
+                                                                          "org.gtk.EggDBus.Name"));
+          /* infer class name if not specified */
+          if (iface_name == NULL)
+            {
+              if (g_str_has_prefix (interface->name, dbus_name_space) &&
+                  interface->name[strlen (dbus_name_space)] == '.')
                 {
-                  g_free (c_file_name);
-                  g_free (h_file_name);
-                  file_print_func_end (FALSE, NULL);
-                  goto out;
+
+                  iface_name = g_strdup (interface->name + strlen (dbus_name_space) + 1);
+
+                  g_printerr ("Inferred GInterface name %s for D-Bus interface %s\n",
+                              iface_name,
+                              interface->name);
                 }
-              if (!file_print_func_end (TRUE, error))
+              else
                 {
-                  g_free (c_file_name);
-                  g_free (h_file_name);
+                  g_set_error (error,
+                               EGG_DBUS_ERROR,
+                               EGG_DBUS_ERROR_FAILED,
+                               "Cannot infer GInterface name for D-Bus interface %s",
+                               interface->name);
                   goto out;
                 }
-              g_printerr ("Wrote %s\n", c_file_name);
-              generated_files = g_slist_prepend (generated_files, g_strdup (c_file_name));
+            }
 
-              g_free (h_file_name);
-              g_free (c_file_name);
+          /* TODO: check this interface name isn't already in use */
 
-              enum_data_list = g_slist_append (enum_data_list, enum_data);
-              enum_data = NULL;
+          iface_name_hyphen = egg_dbus_utils_camel_case_to_hyphen (iface_name);
 
-            } /* for all enums */
+          /* set g_name for all properties and signals */
+          for (m = 0; m < interface->num_properties; m++)
+            {
+              EggDBusInterfacePropertyInfo *prop = (EggDBusInterfacePropertyInfo *) interface->properties + m;
+              prop->g_name = egg_dbus_utils_camel_case_to_hyphen (prop->name);
+            }
+          for (m = 0; m < interface->num_signals; m++)
+            {
+              EggDBusInterfaceSignalInfo *signal = (EggDBusInterfaceSignalInfo *) interface->signals + m;
+              signal->g_name = egg_dbus_utils_camel_case_to_hyphen (signal->name);
+            }
 
-        } /* for all annotations for node */
+          g_free (iface_name_hyphen);
 
-    } /* for all nodes */
+          g_hash_table_insert (all_dbus_interfaces,
+                               g_strdup (iface_name),
+                               (gpointer) interface);
+        }
+    }
 
   ret = TRUE;
 
  out:
+  g_free (name_space_hyphen);
   if (enum_data != NULL)
     enum_data_free (enum_data);
   return ret;
 }
-
 /* ---------------------------------------------------------------------------------------------------- */
 
 static gboolean
-generate_struct_interfaces (GSList   *nodes,
-                            GError **error)
+generate_enums (GError **error)
 {
-  guint n;
-  gboolean ret;
-  GSList *struct_interfaces_to_generate;
   GSList *l;
+  gboolean ret;
 
   ret = FALSE;
-  struct_interfaces_to_generate = NULL;
 
-  /* look for org.gtk.EggDBus.DeclareStruct annotations for top-nodes
-   */
-  for (l = nodes; l != NULL; l = l->next)
+  for (l = enum_data_list; l != NULL; l = l->next)
     {
-      EggDBusInterfaceNodeInfo *node = l->data;
+      EnumData *enum_data = l->data;
+      gchar *h_file_name;
+      gchar *c_file_name;
+      gchar *docbook_file_name;
 
-      for (n = 0; node->annotations != NULL && node->annotations[n].key != NULL; n++)
+      /* now generate Docbook, H and C files for enum_data */
+
+      /* generate docbook file */
+      docbook_file_name = g_strdup_printf ("docbook-enum-%s.xml", enum_data->name);
+      file_print_func_begin (docbook_file_name);
+      if (!enum_generate_docbook (enum_data, error))
         {
-          const EggDBusInterfaceAnnotationInfo *annotation = node->annotations + n;
+          g_free (docbook_file_name);
+          file_print_func_end (FALSE, NULL);
+          goto out;
+        }
+      if (!file_print_func_end (TRUE, error))
+        {
+          g_free (docbook_file_name);
+          goto out;
+        }
+      g_printerr ("Wrote %s\n", docbook_file_name);
+      generated_files = g_slist_prepend (generated_files, g_strdup (docbook_file_name));
+      g_free (docbook_file_name);
 
-          if (strcmp (annotation->key, "org.gtk.EggDBus.DeclareStruct") == 0)
-            {
-              StructData *struct_data;
+      /* generate header file */
+      h_file_name = compute_file_name (name_space, enum_data->name, ".h");
+      file_print_func_begin (h_file_name);
 
-              struct_data = struct_data_new_from_annotation (annotation, error);
-              if (struct_data == NULL)
-                goto out;
+      if (!enum_generate_h_file (enum_data,
+                                 name_space,
+                                 h_file_name,
+                                 enum_data->name,
+                                 error))
+        {
+          g_free (h_file_name);
+          file_print_func_end (FALSE, NULL);
+          goto out;
+        }
+      if (!file_print_func_end (TRUE, error))
+        {
+          g_free (h_file_name);
+          goto out;
+        }
+      g_printerr ("Wrote %s\n", h_file_name);
+      generated_files = g_slist_prepend (generated_files, g_strdup (h_file_name));
 
-              /* delay generation because elements in structs may embed other structs */
-              struct_data_list = g_slist_append (struct_data_list, struct_data);
-            }
+      /* generate c file */
+      c_file_name = compute_file_name (name_space, enum_data->name, ".c");
+      file_print_func_begin (c_file_name);
+
+      if (!enum_generate_c_file (enum_data,
+                                 name_space,
+                                 c_file_name,
+                                 h_file_name,
+                                 enum_data->name,
+                                 error))
+        {
+          g_free (c_file_name);
+          g_free (h_file_name);
+          file_print_func_end (FALSE, NULL);
+          goto out;
         }
-    }
+      if (!file_print_func_end (TRUE, error))
+        {
+          g_free (c_file_name);
+          g_free (h_file_name);
+          goto out;
+        }
+      g_printerr ("Wrote %s\n", c_file_name);
+      generated_files = g_slist_prepend (generated_files, g_strdup (c_file_name));
+
+      g_free (h_file_name);
+      g_free (c_file_name);
+
+    } /* for all enums */
+
+  ret = TRUE;
+
+ out:
+  return ret;
+}
+
+/* ---------------------------------------------------------------------------------------------------- */
+
+static gboolean
+generate_struct_interfaces (GError **error)
+{
+  gboolean ret;
+  GSList *l;
+
+  ret = FALSE;
 
   for (l = struct_data_list; l != NULL; l = l->next)
     {
@@ -1359,157 +1824,88 @@ generate_struct_interfaces (GSList   *nodes,
 /* ---------------------------------------------------------------------------------------------------- */
 
 static gboolean
-generate_dbus_interfaces (GSList   *nodes,
-                          GError  **error)
+generate_dbus_interfaces (GError  **error)
 {
   gboolean ret;
-  GSList *l;
-  guint n;
-  guint m;
-  gchar *name_space_hyphen;
+  GHashTableIter hash_iter;
+  const gchar *iface_name;
+  EggDBusInterfaceInfo *interface;
 
   ret = FALSE;
 
-  name_space_hyphen = egg_dbus_utils_camel_case_to_hyphen (name_space);
-
-  for (l = nodes; l != NULL; l = l->next)
+  g_hash_table_iter_init (&hash_iter, all_dbus_interfaces);
+  while (g_hash_table_iter_next (&hash_iter, (gpointer) &iface_name, (gpointer) &interface))
     {
-      const EggDBusInterfaceNodeInfo *node = l->data;
-
-#if 0
-      GString *s;
-      s = g_string_new (NULL);
-      egg_dbus_interface_node_info_to_xml (node, 2, s);
-      g_printerr ("node:\n%s", s->str);
-      g_string_free (s, TRUE);
-#endif
+      gchar *h_file_name;
+      gchar *c_file_name;
+      gchar *docbook_file_name;
 
-      for (n = 0; n < node->num_interfaces; n++)
+      docbook_file_name = g_strdup_printf ("docbook-interface-%s.xml", interface->name);
+      file_print_func_begin (docbook_file_name);
+      if (!interface_generate_docbook (interface, error))
+        {
+          g_free (docbook_file_name);
+          file_print_func_end (FALSE, NULL);
+          goto out;
+        }
+      if (!file_print_func_end (TRUE, error))
         {
-          const EggDBusInterfaceInfo *interface = node->interfaces + n;
-          gchar *iface_name;
-          gchar *iface_name_hyphen;
-          gchar *h_file_name;
-          gchar *c_file_name;
-          gchar *docbook_file_name;
-
-          iface_name = g_strdup (egg_dbus_interface_annotation_info_lookup (interface->annotations,
-                                                                          "org.gtk.EggDBus.Name"));
-          /* infer class name if not specified */
-          if (iface_name == NULL)
-            {
-              if (g_str_has_prefix (interface->name, dbus_name_space) &&
-                  interface->name[strlen (dbus_name_space)] == '.')
-                {
-
-                  iface_name = g_strdup (interface->name + strlen (dbus_name_space) + 1);
-
-                  g_printerr ("Inferred GInterface name %s for D-Bus interface %s\n",
-                              iface_name,
-                              interface->name);
-                }
-              else
-                {
-                  g_set_error (error,
-                               EGG_DBUS_ERROR,
-                               EGG_DBUS_ERROR_FAILED,
-                               "Cannot infer GInterface name for D-Bus interface %s",
-                               interface->name);
-                  goto out;
-                }
-            }
-
-          /* TODO: check this interface name isn't already in use */
-
-          iface_name_hyphen = egg_dbus_utils_camel_case_to_hyphen (iface_name);
-
-          /* set g_name for all properties and signals */
-          for (m = 0; m < interface->num_properties; m++)
-            {
-              EggDBusInterfacePropertyInfo *prop = (EggDBusInterfacePropertyInfo *) interface->properties + m;
-              prop->g_name = egg_dbus_utils_camel_case_to_hyphen (prop->name);
-            }
-          for (m = 0; m < interface->num_signals; m++)
-            {
-              EggDBusInterfaceSignalInfo *signal = (EggDBusInterfaceSignalInfo *) interface->signals + m;
-              signal->g_name = egg_dbus_utils_camel_case_to_hyphen (signal->name);
-            }
-
-          g_free (iface_name_hyphen);
-
-          docbook_file_name = g_strdup_printf ("docbook-interface-%s.xml", interface->name);
-          file_print_func_begin (docbook_file_name);
-          if (!interface_generate_docbook (interface,
-                                           error))
-            {
-              g_free (docbook_file_name);
-              file_print_func_end (FALSE, NULL);
-              goto out;
-            }
-          if (!file_print_func_end (TRUE, error))
-            {
-              g_free (docbook_file_name);
-              goto out;
-            }
-          g_printerr ("Wrote %s\n", docbook_file_name);
-          generated_files = g_slist_prepend (generated_files, g_strdup (docbook_file_name));
           g_free (docbook_file_name);
+          goto out;
+        }
+      g_printerr ("Wrote %s\n", docbook_file_name);
+      generated_files = g_slist_prepend (generated_files, g_strdup (docbook_file_name));
+      g_free (docbook_file_name);
 
-          h_file_name = compute_file_name (name_space, iface_name, ".h");
-          file_print_func_begin (h_file_name);
-          if (!interface_generate_iface_h_file (interface,
-                                                name_space,
-                                                iface_name,
-                                                h_file_name,
-                                                error))
-            {
-              g_free (h_file_name);
-              file_print_func_end (FALSE, NULL);
-              goto out;
-            }
-          if (!file_print_func_end (TRUE, error))
-            {
-              g_free (h_file_name);
-              goto out;
-            }
-          g_printerr ("Wrote %s\n", h_file_name);
-          generated_files = g_slist_prepend (generated_files, g_strdup (h_file_name));
-
-          c_file_name = compute_file_name (name_space, iface_name, ".c");
-          file_print_func_begin (c_file_name);
-          if (!interface_generate_iface_c_file (interface,
-                                                name_space,
-                                                iface_name,
-                                                c_file_name,
-                                                h_file_name,
-                                                error))
-            {
-              g_free (c_file_name);
-              g_free (h_file_name);
-              file_print_func_end (FALSE, NULL);
-              goto out;
-            }
-          if (!file_print_func_end (TRUE, error))
-            {
-              g_free (c_file_name);
-              g_free (h_file_name);
-              goto out;
-            }
-          g_printerr ("Wrote %s\n", c_file_name);
-          generated_files = g_slist_prepend (generated_files, g_strdup (c_file_name));
-          g_free (c_file_name);
+      h_file_name = compute_file_name (name_space, iface_name, ".h");
+      file_print_func_begin (h_file_name);
+      if (!interface_generate_iface_h_file (interface,
+                                            name_space,
+                                            iface_name,
+                                            h_file_name,
+                                            error))
+        {
           g_free (h_file_name);
+          file_print_func_end (FALSE, NULL);
+          goto out;
+        }
+      if (!file_print_func_end (TRUE, error))
+        {
+          g_free (h_file_name);
+          goto out;
+        }
+      g_printerr ("Wrote %s\n", h_file_name);
+      generated_files = g_slist_prepend (generated_files, g_strdup (h_file_name));
 
-          g_hash_table_insert (all_dbus_interfaces,
-                               g_strdup (iface_name),
-                               (gpointer) interface);
+      c_file_name = compute_file_name (name_space, iface_name, ".c");
+      file_print_func_begin (c_file_name);
+      if (!interface_generate_iface_c_file (interface,
+                                            name_space,
+                                            iface_name,
+                                            c_file_name,
+                                            h_file_name,
+                                            error))
+        {
+          g_free (c_file_name);
+          g_free (h_file_name);
+          file_print_func_end (FALSE, NULL);
+          goto out;
+        }
+      if (!file_print_func_end (TRUE, error))
+        {
+          g_free (c_file_name);
+          g_free (h_file_name);
+          goto out;
         }
+      g_printerr ("Wrote %s\n", c_file_name);
+      generated_files = g_slist_prepend (generated_files, g_strdup (c_file_name));
+      g_free (c_file_name);
+      g_free (h_file_name);
     }
 
   ret = TRUE;
 
  out:
-  g_free (name_space_hyphen);
   return ret;
 }
 
@@ -1553,18 +1949,26 @@ parse (char       **xml_files,
       nodes = g_slist_append (nodes, node);
     }
 
+  /* then extract enums and structs */
+  if (!parse_interfaces_enums_and_structs (nodes, error))
+    goto out;
+
   /* then generate... */
 
-  /* ... GInterfaces for structs */
-  if (!generate_struct_interfaces (nodes, error))
+  /* ... regular expression for Docbook links */
+  if (!create_link_regexs (error))
     goto out;
 
-  /* ... GInterfaces for error domains, enums and flags */
-  if (!generate_enums (nodes, error))
+  /* ... GObjects for structs */
+  if (!generate_struct_interfaces (error))
+    goto out;
+
+  /* ... Enums for error domains, enums and flags */
+  if (!generate_enums (error))
     goto out;
 
   /* ... GInterfaces for all D-Bus interfaces */
-  if (!generate_dbus_interfaces (nodes, error))
+  if (!generate_dbus_interfaces (error))
     goto out;
 
   /* ... <namespace>bindings.[ch] and <namespace>bindingstypes.h */
@@ -1602,6 +2006,8 @@ parse (char       **xml_files,
 
  out:
 
+  free_link_regexs ();
+
   g_hash_table_unref (all_dbus_interfaces);
 
   g_slist_foreach (marshallers_to_generate, (GFunc) g_free, NULL);
diff --git a/src/eggdbus/eggdbusbindingtool.h b/src/eggdbus/eggdbusbindingtool.h
index daac461..fe95bda 100644
--- a/src/eggdbus/eggdbusbindingtool.h
+++ b/src/eggdbus/eggdbusbindingtool.h
@@ -43,13 +43,26 @@ void print_include (const gchar *name_space, const gchar *class_name);
 
 void print_includes (const gchar *name_space, gboolean is_c_file);
 
-gchar*compute_file_name (const gchar *name_space, const gchar *class_name, const gchar *suffix);
+gchar *compute_file_name (const gchar *name_space, const gchar *class_name, const gchar *suffix);
 
-gchar *get_doc_string (const EggDBusInterfaceAnnotationInfo *annotations,
-                       const gchar                          *entity_type);
+/**
+ * DocType:
+ * @DOC_TYPE_GTKDOC:
+ * @DOC_TYPE_DOCBOOK:
+ *
+ * The target consuming the documentation; used for translating method_calls(),
+ * #Type::signal, #Type:property and %CONSTANTS to a suitable representation.
+ */
+typedef enum
+{
+  DOC_TYPE_GTKDOC,
+  DOC_TYPE_DOCBOOK
+} DocType;
 
-gchar *get_summary_doc_string (const EggDBusInterfaceAnnotationInfo *annotations,
-                               const gchar                          *entity_type);
+gchar *get_doc         (const EggDBusInterfaceAnnotationInfo *annotations,
+                        DocType                               type);
+gchar *get_doc_summary (const EggDBusInterfaceAnnotationInfo *annotations,
+                        DocType                               type);
 
 G_END_DECLS
 
diff --git a/src/eggdbus/enum.c b/src/eggdbus/enum.c
index 9bebdd0..c4eb2de 100644
--- a/src/eggdbus/enum.c
+++ b/src/eggdbus/enum.c
@@ -488,8 +488,8 @@ enum_generate_h_file (EnumData         *enum_data,
   full_instance_name = g_strdup_printf ("%s%s", name_space, enum_data->name);
   full_instance_name_uscore = egg_dbus_utils_camel_case_to_uscore (full_instance_name);
 
-  enum_summary_doc_string = get_summary_doc_string (enum_data->annotations, "Enum");
-  enum_doc_string = get_doc_string (enum_data->annotations, "Enum");
+  enum_summary_doc_string = get_doc_summary (enum_data->annotations, DOC_TYPE_GTKDOC);
+  enum_doc_string = get_doc (enum_data->annotations, DOC_TYPE_GTKDOC);
 
   header_file_protection = g_strdup_printf ("__%s_%s_H",
                                             name_space_uscore_upper,
@@ -568,7 +568,7 @@ enum_generate_h_file (EnumData         *enum_data,
                enum_data->name_uscore_upper,
                elem->g_name_uscore_upper);
 
-      doc_string = get_doc_string (elem->annotations, "Enum Member");
+      doc_string = get_doc (elem->annotations, DOC_TYPE_GTKDOC);
       g_print ("%s\n", doc_string);
       g_free (doc_string);
     }
@@ -699,8 +699,8 @@ enum_generate_c_file (EnumData      *enum_data,
   full_instance_name_uscore = egg_dbus_utils_camel_case_to_uscore (full_instance_name);
   full_instance_name_uscore_upper = g_ascii_strup (full_instance_name_uscore, -1);
 
-  enum_summary_doc_string = get_summary_doc_string (enum_data->annotations, "Enum");
-  enum_doc_string = get_doc_string (enum_data->annotations, "Enum");
+  enum_summary_doc_string = get_doc_summary (enum_data->annotations, DOC_TYPE_GTKDOC);
+  enum_doc_string = get_doc (enum_data->annotations, DOC_TYPE_GTKDOC);
 
   g_print ("\n"
            "/* File: %s\n"
diff --git a/src/eggdbus/interface.c b/src/eggdbus/interface.c
index 2e74c4d..03fa5d6 100644
--- a/src/eggdbus/interface.c
+++ b/src/eggdbus/interface.c
@@ -40,9 +40,9 @@ typedef enum {
 } MethodType;
 
 static gchar *
-get_doc_string_for_arg (const EggDBusInterfaceArgInfo *arg)
+get_doc_for_arg (const EggDBusInterfaceArgInfo *arg)
 {
-  return get_doc_string (arg->annotations, "Argument");
+  return get_doc (arg->annotations, DOC_TYPE_GTKDOC);
 }
 
 static gboolean
@@ -74,7 +74,7 @@ print_gtkdoc_for_args (const EggDBusInterfaceArgInfo  *args,
 
       arg_name_uscore = egg_dbus_utils_camel_case_to_uscore (arg->name);
 
-      arg_doc_string = get_doc_string_for_arg (arg);
+      arg_doc_string = get_doc_for_arg (arg);
 
       free_info = NULL;
 
@@ -196,15 +196,16 @@ print_method_doc (const EggDBusInterfaceMethodInfo  *method,
       g_print (" * @cancellable: A #GCancellable or %%NULL.\n"
                " * @error: Return location for error.\n");
 
-      method_doc_string = get_doc_string (method->annotations, "Method");
+      method_doc_string = get_doc (method->annotations, DOC_TYPE_GTKDOC);
       g_print (" *\n"
                " * %s\n",
                method_doc_string);
 
       g_print (" *\n"
-               " * This function synchronously invokes the <literal>%s.%s()</literal> method on the object represented by @instance.\n"
+               " * This function synchronously invokes the <link linkend=\"eggdbus-method-%s.%s\">%s<!-- -->()</link> method on the <link linkend=\"eggdbus-interface-%s\">%s</link> interface on the object represented by @instance.\n"
                " * See %s_%s_%s() for the asynchronous version of this function.\n",
-               interface->name, method->name,
+               interface->name, method->name, method->name,
+               interface->name, interface->name,
                name_space_uscore, iface_name_uscore, method_name_uscore);
 
     }
@@ -226,18 +227,20 @@ print_method_doc (const EggDBusInterfaceMethodInfo  *method,
                " * @callback: Callback to invoke when the reply is ready.\n"
                " * @user_data: User data to pass to @callback.\n");
 
-      method_doc_string = get_doc_string (method->annotations, "Method");
+      method_doc_string = get_doc (method->annotations, DOC_TYPE_GTKDOC);
       g_print (" *\n"
                " * %s\n",
                method_doc_string);
 
       g_print (" *\n"
-               " * This function asynchronously invokes the <literal>%s.%s()</literal> method\n"
+               " * This function asynchronously invokes the <link linkend=\"eggdbus-method-%s.%s\">%s<!-- -->()</link> method\n"
+               " * on the <link linkend=\"eggdbus-interface-%s\">%s</link> interface\n"
                " * on the object represented by @instance.\n"
                " * When the reply is ready, @callback will be called (on the main thread).\n"
                " * You can then call %s_%s_%s_finish() to get the result.\n"
                " * See %s_%s_%s_sync() for the synchronous version of this function.\n",
-               interface->name, method->name,
+               interface->name, method->name, method->name,
+               interface->name, interface->name,
                name_space_uscore, iface_name_uscore, method_name_uscore,
                name_space_uscore, iface_name_uscore, method_name_uscore);
 
@@ -278,10 +281,12 @@ print_method_doc (const EggDBusInterfaceMethodInfo  *method,
       g_print (" * @method_invocation: A #EggDBusMethodInvocation.\n");
 
       g_print (" *\n"
-               " * Function to be called by implementers of the <literal>%s</literal>\n"
-               " * D-Bus interface to finish handling the <literal>%s()</literal> method.\n",
-               interface->name,
-               method->name);
+               " * Function to be called by implementers of the\n"
+               " * <link linkend=\"eggdbus-interface-%s\">%s</link>\n"
+               " * D-Bus interface to finish handling the\n"
+               " * <link linkend=\"eggdbus-method-%s.%s\">%s<!-- -->()</link> method.\n",
+               interface->name, interface->name,
+               interface->name, method->name, method->name);
     }
 
   g_print (" *\n");
@@ -741,7 +746,7 @@ interface_generate_iface_h_file (const EggDBusInterfaceInfo   *interface,
            " *\n"
            " * Returns: An instance derived from #EggDBusInterfaceProxy that implements the\n"
            " *          #%s interface. This instance can be used to access the\n"
-           " *          <literal>%s</literal> D-Bus interface on the remote\n"
+           " *          <link linkend=\"eggdbus-interface-%s\">%s</link> D-Bus interface on the remote\n"
            " *          object represented by @object_proxy. Do not ref or unref the returned instance,\n"
            " *          it is owned by @object_proxy.\n"
            " */\n"
@@ -749,7 +754,7 @@ interface_generate_iface_h_file (const EggDBusInterfaceInfo   *interface,
            "\n",
            name_space_uscore_upper, iface_name_uscore_upper,
            full_instance_name,
-           interface->name,
+           interface->name, interface->name,
            name_space_uscore_upper, iface_name_uscore_upper,
            name_space_uscore_upper, iface_name_uscore_upper,
            name_space_uscore_upper, iface_name_uscore_upper);
@@ -765,7 +770,7 @@ interface_generate_iface_h_file (const EggDBusInterfaceInfo   *interface,
       gchar *method_doc_string;
 
       method_name_uscore = egg_dbus_utils_camel_case_to_uscore (method->name);
-      method_doc_string = get_doc_string (method->annotations, "Method");
+      method_doc_string = get_doc (method->annotations, DOC_TYPE_GTKDOC);
 
       g_print (" * @handle_%s: %s\n",
                method_name_uscore,
@@ -775,8 +780,9 @@ interface_generate_iface_h_file (const EggDBusInterfaceInfo   *interface,
       g_free (method_doc_string);
     }
   g_print (" *\n"
-           " * Interface VTable for implementing the <literal>%s</literal> D-Bus interface.\n"
+           " * Interface VTable for implementing the <link linkend=\"eggdbus-interface-%s\">%s</link> D-Bus interface.\n"
            " */\n",
+           interface->name,
            interface->name);
 
   /* iface vtable */
@@ -1672,8 +1678,8 @@ interface_generate_iface_c_file (const EggDBusInterfaceInfo  *interface,
   full_instance_name_uscore = egg_dbus_utils_camel_case_to_uscore (full_instance_name);
   full_instance_name_hyphen = egg_dbus_utils_camel_case_to_hyphen (full_instance_name);
 
-  interface_summary_doc_string = get_summary_doc_string (interface->annotations, "Interface");
-  interface_doc_string = get_doc_string (interface->annotations, "Interface");
+  interface_summary_doc_string = get_doc_summary (interface->annotations, DOC_TYPE_GTKDOC);
+  interface_doc_string = get_doc (interface->annotations, DOC_TYPE_GTKDOC);
 
   g_print ("\n"
            "/* File: %s\n"
@@ -2023,7 +2029,7 @@ interface_generate_iface_c_file (const EggDBusInterfaceInfo  *interface,
           g_assert_not_reached ();
         }
 
-      prop_doc_string = get_doc_string (prop->annotations, "Property");
+      prop_doc_string = get_doc (prop->annotations, DOC_TYPE_GTKDOC);
 
       g_print ("      /**\n"
                "       * %s:%s:\n"
@@ -2155,7 +2161,7 @@ interface_generate_iface_c_file (const EggDBusInterfaceInfo  *interface,
                                   error))
         goto out;
 
-      signal_doc_string = get_doc_string (signal->annotations, "Signal");
+      signal_doc_string = get_doc (signal->annotations, DOC_TYPE_GTKDOC);
       g_print ("       *\n"
                "       * %s\n",
                signal_doc_string);
@@ -3187,12 +3193,10 @@ interface_generate_iface_c_file (const EggDBusInterfaceInfo  *interface,
 
 
       g_print (" *\n"
-               " * Type safe wrapper for emitting the #%s::%s signal\n"
-               " * on the <literal>%s</literal> D-Bus interface.\n"
+               " * Type safe wrapper for emitting the #%s::%s signal.\n"
                " *\n"
                " **/\n",
-               full_instance_name, signal->g_name,
-               interface->name);
+               full_instance_name, signal->g_name);
 
       if (!print_signal_emitter_prototype (signal,
                                            name_space_uscore,
diff --git a/src/eggdbus/org.freedesktop.DBus.Peer.xml b/src/eggdbus/org.freedesktop.DBus.Peer.xml
index dd552ef..0f21c23 100644
--- a/src/eggdbus/org.freedesktop.DBus.Peer.xml
+++ b/src/eggdbus/org.freedesktop.DBus.Peer.xml
@@ -3,7 +3,7 @@
 <node name="/">
 
   <interface name="org.freedesktop.DBus.Peer">
-    <annotation name="org.gtk.EggDBus.DocString" value="All D-Bus objects are supposed to implement the <literal>org.freedesktop.DBus.Peer</literal> D-Bus interface. The interface is designed to be a minimal interface for checking whether the other end is reachable and, if so, what machine hosts the object."/>
+    <annotation name="org.gtk.EggDBus.DocString" value="All D-Bus objects are supposed to implement the #org.freedesktop.DBus.Peer D-Bus interface. The interface is designed to be a minimal interface for checking whether the other end is reachable and, if so, what machine hosts the object."/>
     <annotation name="org.gtk.EggDBus.DocString.Summary" value="Minimal peering interface"/>
 
     <method name="Ping">
diff --git a/src/eggdbus/org.freedesktop.DBus.Properties.xml b/src/eggdbus/org.freedesktop.DBus.Properties.xml
index a1a2d64..d3c0df7 100644
--- a/src/eggdbus/org.freedesktop.DBus.Properties.xml
+++ b/src/eggdbus/org.freedesktop.DBus.Properties.xml
@@ -3,7 +3,7 @@
 <node name="/">
 
   <interface name="org.freedesktop.DBus.Properties">
-    <annotation name="org.gtk.EggDBus.DocString" value="Many native APIs will have a concept of object <emphasis>properties</emphasis> or <emphasis>attributes</emphasis>. These can be exposed via the <literal>org.freedesktop.DBus.Properties</literal> interface. The available properties and whether they are writable can be determined by using the #Introspectable interface."/>
+    <annotation name="org.gtk.EggDBus.DocString" value="Many native APIs will have a concept of object <emphasis>properties</emphasis> or <emphasis>attributes</emphasis>. These can be exposed via the #org.freedesktop.DBus.Properties interface. The available properties and whether they are writable can be determined by using the #org.freedesktop.DBus.Introspectable interface."/>
     <annotation name="org.gtk.EggDBus.DocString.Summary" value="Properties interface"/>
 
     <method name="Get">
diff --git a/src/eggdbus/org.freedesktop.DBus.xml b/src/eggdbus/org.freedesktop.DBus.xml
index 7485532..8ac3eac 100644
--- a/src/eggdbus/org.freedesktop.DBus.xml
+++ b/src/eggdbus/org.freedesktop.DBus.xml
@@ -3,18 +3,18 @@
 <node>
 
   <annotation name="org.gtk.EggDBus.DeclareFlags" value="RequestNameFlags">
-    <annotation name="org.gtk.EggDBus.DocString" value="Flags used in the RequestName() method."/>
-    <annotation name="org.gtk.EggDBus.DocString.Summary" value="Flags used in the RequestName() method"/>
+    <annotation name="org.gtk.EggDBus.DocString.Summary" value="Flags used when requesting a name"/>
+    <annotation name="org.gtk.EggDBus.DocString" value="Flags used in the org.freedesktop.DBus.RequestName() method."/>
 
   <!-- ################################################################################ -->
 
     <annotation name="org.gtk.EggDBus.Flags.Member" value="AllowReplacement">
       <annotation name="org.gtk.EggDBus.Flags.Member.Value" value="0x01"/>
-      <annotation name="org.gtk.EggDBus.DocString" value="If an application A specifies this flag and succeeds in becoming the owner of the name, and another application B later calls Request() with the #ReplaceExisting flag, then application A will lose ownership and receive a NameLost signal, and application B will become the new owner. If #AllowReplacement is not specified by application A, or #ReplaceExisiting is not specified by application B, then application B will not replace application A as the owner."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="If an application A specifies this flag and succeeds in becoming the owner of the name, and another application B later calls org.freedesktop.DBus.RequestName() with the %RequestNameFlags.ReplaceExisting flag, then application A will lose ownership and receive a #org.freedesktop.DBus::NameLost signal, and application B will become the new owner. If %RequestNameFlags.AllowReplacement is not specified by application A, or %RequestNameFlags.ReplaceExisting is not specified by application B, then application B will not replace application A as the owner."/>
     </annotation>
     <annotation name="org.gtk.EggDBus.Flags.Member" value="ReplaceExisting">
       <annotation name="org.gtk.EggDBus.Flags.Member.Value" value="0x02"/>
-      <annotation name="org.gtk.EggDBus.DocString" value="Try to replace the current owner if there is one. If this flag is not set the application will only become the owner of the name if there is no current owner. If this flag is set, the application will replace the current owner if the current owner specified #AllowReplacement."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="Try to replace the current owner if there is one. If this flag is not set the application will only become the owner of the name if there is no current owner. If this flag is set, the application will replace the current owner if the current owner specified %RequestNameFlags.AllowReplacement."/>
     </annotation>
     <annotation name="org.gtk.EggDBus.Flags.Member" value="DoNotQueue">
       <annotation name="org.gtk.EggDBus.Flags.Member.Value" value="0x04"/>
@@ -23,22 +23,22 @@
   </annotation>
 
   <annotation name="org.gtk.EggDBus.DeclareEnum" value="RequestNameReply">
-    <annotation name="org.gtk.EggDBus.DocString" value="Return values for the RequestName() method."/>
-    <annotation name="org.gtk.EggDBus.DocString.Summary" value="Return values for the RequestName() method"/>
+    <annotation name="org.gtk.EggDBus.DocString.Summary" value="Return values when requesting a name"/>
+    <annotation name="org.gtk.EggDBus.DocString" value="Return values for the org.freedesktop.DBus.RequestName() method"/>
 
   <!-- ################################################################################ -->
 
     <annotation name="org.gtk.EggDBus.Enum.Member" value="PrimaryOwner">
       <annotation name="org.gtk.EggDBus.Enum.Member.Value" value="1"/>
-      <annotation name="org.gtk.EggDBus.DocString" value="The caller is now the primary owner of the name, replacing any previous owner. Either the name had no owner before, or the caller specified #ReplaceExisting and the current owner specified #AllowReplacement."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="The caller is now the primary owner of the name, replacing any previous owner. Either the name had no owner before, or the caller specified %RequestNameFlags.ReplaceExisting and the current owner specified %RequestNameFlags.AllowReplacement."/>
     </annotation>
     <annotation name="org.gtk.EggDBus.Enum.Member" value="InQueue">
       <annotation name="org.gtk.EggDBus.Enum.Member.Value" value="2"/>
-      <annotation name="org.gtk.EggDBus.DocString" value="The name already had an owner, #DoNotQueue was not specified, and either the current owner did not specify #AllowReplacement or the requesting application did not specify #ReplaceExisting."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="The name already had an owner, %RequestNameFlags.DoNotQueue was not specified, and either the current owner did not specify %RequestNameFlags.AllowReplacement or the requesting application did not specify %RequestNameFlags.ReplaceExisting."/>
     </annotation>
     <annotation name="org.gtk.EggDBus.Enum.Member" value="Exists">
       <annotation name="org.gtk.EggDBus.Enum.Member.Value" value="3"/>
-      <annotation name="org.gtk.EggDBus.DocString" value="The name already has an owner, #DoNotQueue was specified, and either #AllowReplacement was not specified by the current owner, or #ReplaceExisting was not specified by the requesting application."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="The name already has an owner, %RequestNameFlags.DoNotQueue was specified, and either %RequestNameFlags.AllowReplacement was not specified by the current owner, or %RequestNameFlags.ReplaceExisting was not specified by the requesting application."/>
     </annotation>
     <annotation name="org.gtk.EggDBus.Enum.Member" value="AlreadyOwned">
       <annotation name="org.gtk.EggDBus.Enum.Member.Value" value="4"/>
@@ -49,8 +49,8 @@
   <!-- ################################################################################ -->
 
   <annotation name="org.gtk.EggDBus.DeclareEnum" value="ReleaseNameReply">
-    <annotation name="org.gtk.EggDBus.DocString" value="Return values for the ReleaseName() method."/>
-    <annotation name="org.gtk.EggDBus.DocString.Summary" value="Return values for the ReleaseName() method"/>
+    <annotation name="org.gtk.EggDBus.DocString.Summary" value="Return values for the releasing a name"/>
+    <annotation name="org.gtk.EggDBus.DocString" value="Return values for the org.freedesktop.DBus.ReleaseName() method."/>
 
     <annotation name="org.gtk.EggDBus.Enum.Member" value="Released">
       <annotation name="org.gtk.EggDBus.Enum.Member.Value" value="1"/>
@@ -69,8 +69,8 @@
   <!-- ################################################################################ -->
 
   <annotation name="org.gtk.EggDBus.DeclareEnum" value="StartServiceByNameReply">
-    <annotation name="org.gtk.EggDBus.DocString" value="Return values for the StartServiceByName() method."/>
-    <annotation name="org.gtk.EggDBus.DocString.Summary" value="Return values for the StartServiceByName() method"/>
+    <annotation name="org.gtk.EggDBus.DocString.Summary" value="Return values for starting a service"/>
+    <annotation name="org.gtk.EggDBus.DocString" value="Return values for the org.freedesktop.DBus.StartServiceByName() method."/>
 
     <annotation name="org.gtk.EggDBus.Enum.Member" value="Success">
       <annotation name="org.gtk.EggDBus.Enum.Member.Value" value="1"/>
@@ -85,13 +85,13 @@
   <!-- ################################################################################ -->
 
   <interface name="org.freedesktop.DBus">
-    <annotation name="org.gtk.EggDBus.DocString" value="The <literal>org.freedesktop.DBus</literal> D-Bus interface is implemented by message bus daemons. Normally applications only use the RequestName() method to claim a well-known name on the message bus."/>
     <annotation name="org.gtk.EggDBus.DocString.Summary" value="Message bus daemon interface"/>
+    <annotation name="org.gtk.EggDBus.DocString" value="The #org.freedesktop.DBus D-Bus interface is implemented by message bus daemons. Normally applications only use the org.freedesktop.DBus.RequestName() method to claim a well-known name on the message bus."/>
 
     <annotation name="org.gtk.EggDBus.Name" value="Bus"/>
 
     <method name="Hello">
-      <annotation name="org.gtk.EggDBus.DocString" value="Before an application is able to send messages to other applications it must invoke this method on the message bus to obtain a unique name. If an application without a unique name tries to send a message to another application, or a message to the message bus itself that isn't the Hello() method, it will be disconnected from the bus. There is no corresponding <emphasis>disconnect</emphasis> request; if a client wishes to disconnect from the bus, it simply closes the socket (or other communication channel)."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="Before an application is able to send messages to other applications it must invoke this method on the message bus to obtain a unique name. If an application without a unique name tries to send a message to another application, or a message to the message bus itself that isn't the org.freedesktop.DBus.Hello() method, it will be disconnected from the bus. There is no corresponding <emphasis>disconnect</emphasis> request; if a client wishes to disconnect from the bus, it simply closes the socket (or other communication channel)."/>
 
       <arg direction="out" type="s" name="assigned_name">
         <annotation name="org.gtk.EggDBus.DocString" value="Unique name assigned to the connection."/>
@@ -99,7 +99,7 @@
     </method>
 
     <method name="RequestName">
-      <annotation name="org.gtk.EggDBus.DocString" value="This method call should be invoked on the <literal>org.freedesktop.DBus</literal> name to request the message bus to assign the given name to the method caller. Each name maintains a queue of possible owners, where the head of the queue is the primary or current owner of the name. Each potential owner in the queue maintains the #AllowReplacement and #DoNotQueue settings from its latest RequestName() call. See the D-Bus specification for more details."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="This method call should be invoked on the <literal>org.freedesktop.DBus</literal> name to request the message bus to assign the given name to the method caller. Each name maintains a queue of possible owners, where the head of the queue is the primary or current owner of the name. Each potential owner in the queue maintains the %RequestNameFlags.AllowReplacement and %RequestNameFlags.DoNotQueue settings from its latest org.freedesktop.DBus.RequestName() call. See the D-Bus specification for more details."/>
 
       <arg direction="in" type="s" name="name">
         <annotation name="org.gtk.EggDBus.DocString" value="Name to request."/>
@@ -177,7 +177,7 @@
     </method>
 
     <method name="AddMatch">
-      <annotation name="org.gtk.EggDBus.DocString" value="Adds a match rule to match messages going through the message bus. If the bus does not have enough resources the #OOM error is returned. See the D-Bus specification for more information about match rules."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="Adds a match rule to match messages going through the message bus. If the bus does not have enough resources the %org.freedesktop.DBus.Error.OOM error is returned. See the D-Bus specification for more information about match rules."/>
 
       <arg direction="in" type="s" name="rule">
         <annotation name="org.gtk.EggDBus.DocString" value="Match rule to add to the connection."/>
@@ -185,7 +185,7 @@
     </method>
 
     <method name="RemoveMatch">
-      <annotation name="org.gtk.EggDBus.DocString" value="Removes the first rule that matches. If the rule is not found the org.freedesktop.DBus.Error.MatchRuleNotFound  error is returned. See the D-Bus specification for more information about match rules."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="Removes the first rule that matches. If the rule is not found the %org.freedesktop.DBus.Error.MatchRuleNotFound  error is returned. See the D-Bus specification for more information about match rules."/>
 
       <arg direction="in" type="s" name="rule">
         <annotation name="org.gtk.EggDBus.DocString" value="Match rule to remove from the connection."/>
@@ -193,7 +193,7 @@
     </method>
 
     <method name="GetNameOwner">
-      <annotation name="org.gtk.EggDBus.DocString" value="Returns the unique connection name of the primary owner of the name given. If the requested name doesn't have an owner, returns a #NameHasNoOwner error."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="Returns the unique connection name of the primary owner of the name given. If the requested name doesn't have an owner, returns a %org.freedesktop.DBus.Error.NameHasNoOwner error."/>
 
       <arg direction="in" type="s" name="name">
         <annotation name="org.gtk.EggDBus.DocString" value="Name to get owner of."/>
@@ -215,7 +215,7 @@
     </method>
 
     <method name="GetConnectionUnixUser">
-      <annotation name="org.gtk.EggDBus.DocString" value="Returns the UNIX user id of the process connected to the server. If unable to determine it, a #Failed error is returned."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="Returns the UNIX user id of the process connected to the server. If unable to determine it, a %org.freedesktop.DBus.Error.Failed error is returned."/>
 
       <arg direction="in" type="s" name="name">
         <annotation name="org.gtk.EggDBus.DocString" value="Name of the connection to query."/>
@@ -227,7 +227,7 @@
     </method>
 
     <method name="GetConnectionUnixProcessID">
-      <annotation name="org.gtk.EggDBus.DocString" value="Returns the UNIX process id of the process connected to the server. If unable to determine it, a #Failed error is returned."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="Returns the UNIX process id of the process connected to the server. If unable to determine it, a %org.freedesktop.DBus.Error.Failed error is returned."/>
 
       <arg direction="in" type="s" name="name">
         <annotation name="org.gtk.EggDBus.DocString" value="Name of the connection to query."/>
@@ -239,7 +239,7 @@
     </method>
 
     <method name="GetAdtAuditSessionData">
-      <annotation name="org.gtk.EggDBus.DocString" value="Returns the Solaris/ADT auditing data of the process connected to the server. If unable to determine it, a #AdtAuditDataUnknown error is returned."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="Returns the Solaris/ADT auditing data of the process connected to the server. If unable to determine it, a %org.freedesktop.DBus.Error.AdtAuditDataUnknown error is returned."/>
 
       <arg direction="in" type="s" name="name">
         <annotation name="org.gtk.EggDBus.DocString" value="Name of the connection to query."/>
@@ -250,7 +250,7 @@
     </method>
 
     <method name="GetConnectionSELinuxSecurityContext">
-      <annotation name="org.gtk.EggDBus.DocString" value="Returns the SELinux security context of the process connected to the server. If unable to determine it, a #SELinuxSecurityContextUnknown error is returned."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="Returns the SELinux security context of the process connected to the server. If unable to determine it, a %org.freedesktop.DBus.Error.SELinuxSecurityContextUnknown error is returned."/>
 
       <arg direction="in" type="s" name="name">
         <annotation name="org.gtk.EggDBus.DocString" value="Name of the connection to query."/>
diff --git a/src/eggdbus/struct.c b/src/eggdbus/struct.c
index def9cec..c764ed0 100644
--- a/src/eggdbus/struct.c
+++ b/src/eggdbus/struct.c
@@ -462,8 +462,8 @@ struct_generate_c_file (StructData    *struct_data,
   full_instance_name_uscore = egg_dbus_utils_camel_case_to_uscore (full_instance_name);
   full_instance_name_uscore_upper = g_ascii_strup (full_instance_name_uscore, -1);
 
-  struct_summary_doc_string = get_summary_doc_string (struct_data->annotations, "Struct");
-  struct_doc_string = get_doc_string (struct_data->annotations, "Struct");
+  struct_summary_doc_string = get_doc_summary (struct_data->annotations, DOC_TYPE_GTKDOC);
+  struct_doc_string = get_doc (struct_data->annotations, DOC_TYPE_GTKDOC);
 
   g_print ("\n"
            "/* File: %s\n"
@@ -539,7 +539,7 @@ struct_generate_c_file (StructData    *struct_data,
       if (type_name == NULL)
         goto out;
 
-      doc_string = get_doc_string (struct_data->elements[n]->annotations, "Structure Element");
+      doc_string = get_doc (struct_data->elements[n]->annotations, DOC_TYPE_GTKDOC);
 
       g_print ("/**\n"
                " * %s_%s_get_%s:\n"
@@ -618,7 +618,7 @@ struct_generate_c_file (StructData    *struct_data,
       if (type_name == NULL)
         goto out;
 
-      doc_string = get_doc_string (struct_data->elements[n]->annotations, "Structure Element");
+      doc_string = get_doc (struct_data->elements[n]->annotations, DOC_TYPE_GTKDOC);
 
       g_print ("/**\n"
                " * %s_%s_set_%s:\n"
@@ -683,7 +683,7 @@ struct_generate_c_file (StructData    *struct_data,
     {
       gchar *doc_string;
 
-      doc_string = get_doc_string (struct_data->elements[n]->annotations, "Structure Element");
+      doc_string = get_doc (struct_data->elements[n]->annotations, DOC_TYPE_GTKDOC);
 
       g_print (" * @%s: %s\n",
                struct_data->elements[n]->name,
diff --git a/src/tests/com.example.Frob.xml b/src/tests/com.example.Frob.xml
index f29e997..9027d7f 100644
--- a/src/tests/com.example.Frob.xml
+++ b/src/tests/com.example.Frob.xml
@@ -95,8 +95,8 @@
   <!-- -->
 
   <interface name="com.example.Frob">
-    <annotation name="org.gtk.EggDBus.DocString" value="The #Frob interface wraps the D-Bus interface <literal>com.example.Frob</literal>. It is used in the EggDBus test suite."/>
     <annotation name="org.gtk.EggDBus.DocString.Summary" value="Frob interface used for testing"/>
+    <annotation name="org.gtk.EggDBus.DocString" value="<para>The #com.example.Frob interface is used in the EggDBus test suite.</para><para>Test of symbol/constant/method/signal/property resolution: Link to method com.example.Frob.HelloWorld(). And a link to a signal #com.example.Frob::SignalWithPrimitiveTypes. And a property #com.example.Frob:foo. And also a struct #Point. And an error %com.example.Error.FluxCapacitorFailure. And a flag value %CreateFlags.LogAttempt. And an enum %Vehicle.Truck. Link to an enumeration #Vehicle. Link to a collection of errors #com.example.Error. And a collection of flags #DeleteFlags. %TRUE. %FALSE. That's it.</para>"/>
 
     <method name="HelloWorld">
       <arg direction="in"  type="s" name="hello_message" />