preliminary support for generating Docbook docs for D-Bus interfaces

Right now it's very similar to spec-to-docbook.xsl written by Jon
McCann and David Zeuthen. Since EggDBus introspection XML is a lot
richer (flags, enums, error domains, structs etc.) there's still some
room for improvement.

7 files changed, 629 insertions, 65 deletions

diff --git a/docs/eggdbus/Makefile.am b/docs/eggdbus/Makefile.am
index 0817abf..e6b3b37 100644
--- a/docs/eggdbus/Makefile.am
+++ b/docs/eggdbus/Makefile.am
@@ -56,9 +56,16 @@ MKDB_OPTIONS=--sgml-mode --output-format=xml
 MKTMPL_OPTIONS=
 
 # Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE)
-content_files =  			    	\
-	../version.xml			    	\
-	../man/eggdbus-binding-tool.xml	    	\
+content_files =  			    						\
+	../version.xml			    						\
+	../man/eggdbus-binding-tool.xml	    						\
+	../../src/eggdbus/docbook-interface-org.freedesktop.DBus.xml			\
+	../../src/eggdbus/docbook-interface-org.freedesktop.DBus.Peer.xml		\
+	../../src/eggdbus/docbook-interface-org.freedesktop.DBus.Properties.xml		\
+	../../src/eggdbus/docbook-interface-org.freedesktop.DBus.Introspectable.xml	\
+	../../src/tests/docbook-interface-com.example.Frob.xml				\
+	../../src/tests/docbook-interface-com.example.Tweak.xml				\
+	../../src/tests/docbook-interface-com.example.Twiddle.xml			\
 	$(NULL)
 
 # Images to copy into HTML directory
diff --git a/docs/eggdbus/eggdbus-docs.xml b/docs/eggdbus/eggdbus-docs.xml
index c8e3a37..3bf5323 100644
--- a/docs/eggdbus/eggdbus-docs.xml
+++ b/docs/eggdbus/eggdbus-docs.xml
@@ -129,6 +129,17 @@
       <xi:include href="../tests/xml/testvehicle.xml"/>
     </chapter>
 
+    <chapter id="example-dbus">
+      <title>Example of Generated D-Bus docs</title>
+      <xi:include href="../../src/eggdbus/docbook-interface-org.freedesktop.DBus.xml"/>
+      <xi:include href="../../src/eggdbus/docbook-interface-org.freedesktop.DBus.Peer.xml"/>
+      <xi:include href="../../src/eggdbus/docbook-interface-org.freedesktop.DBus.Properties.xml"/>
+      <xi:include href="../../src/eggdbus/docbook-interface-org.freedesktop.DBus.Introspectable.xml"/>
+      <xi:include href="../../src/tests/docbook-interface-com.example.Frob.xml"/>
+      <xi:include href="../../src/tests/docbook-interface-com.example.Tweak.xml"/>
+      <xi:include href="../../src/tests/docbook-interface-com.example.Twiddle.xml"/>
+    </chapter>
+
   </reference>
 
   <reference id="ref-programs">
diff --git a/src/eggdbus/Makefile.am b/src/eggdbus/Makefile.am
index 65dda6f..e744b49 100644
--- a/src/eggdbus/Makefile.am
+++ b/src/eggdbus/Makefile.am
@@ -147,29 +147,9 @@ eggdbus-built-sources.stamp : eggdbus-binding-tool Makefile.am org.freedesktop.D
 		--stamp-file eggdbus-built-sources.stamp						\
 		$(NULL)
 
-# keep in sync with contents of eggdbus-built-sources.stamp
+# keep in sync with contents of eggdbus-built-sources.stamp (Thanks autotools)
 #
-egg_dbus_built_sources = 						\
-	eggdbusbindingsmarshal.c					\
-	eggdbusbindingsmarshal.h					\
-	eggdbusbindingsmarshal.list					\
-	eggdbusintrospectable.c						\
-	eggdbusintrospectable.h						\
-	eggdbusproperties.c						\
-	eggdbusproperties.h						\
-	eggdbuspeer.c							\
-	eggdbuspeer.h							\
-	eggdbusbus.c							\
-	eggdbusbus.h							\
-	eggdbusstartservicebynamereply.c				\
-	eggdbusstartservicebynamereply.h				\
-	eggdbusreleasenamereply.c					\
-	eggdbusreleasenamereply.h					\
-	eggdbusrequestnamereply.c					\
-	eggdbusrequestnamereply.h					\
-	eggdbusrequestnameflags.c					\
-	eggdbusrequestnameflags.h					\
-	$(NULL)
+egg_dbus_built_sources = eggdbusbindingsmarshal.c eggdbusbindingsmarshal.h eggdbusbindingsmarshal.list eggdbusintrospectable.c eggdbusintrospectable.h docbook-interface-org.freedesktop.DBus.Introspectable.xml eggdbusproperties.c eggdbusproperties.h docbook-interface-org.freedesktop.DBus.Properties.xml eggdbuspeer.c eggdbuspeer.h docbook-interface-org.freedesktop.DBus.Peer.xml eggdbusbus.c eggdbusbus.h docbook-interface-org.freedesktop.DBus.xml eggdbusstartservicebynamereply.c eggdbusstartservicebynamereply.h eggdbusreleasenamereply.c eggdbusreleasenamereply.h eggdbusrequestnamereply.c eggdbusrequestnamereply.h eggdbusrequestnameflags.c eggdbusrequestnameflags.h
 
 enum_headers =                        					\
 	eggdbusinterface.h						\
diff --git a/src/eggdbus/eggdbusbindingtool.c b/src/eggdbus/eggdbusbindingtool.c
index 47a999b..0bfb9aa 100644
--- a/src/eggdbus/eggdbusbindingtool.c
+++ b/src/eggdbus/eggdbusbindingtool.c
@@ -1353,6 +1353,7 @@ generate_dbus_interfaces (GSList   *nodes,
           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"));
@@ -1398,6 +1399,24 @@ generate_dbus_interfaces (GSList   *nodes,
 
           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);
+
           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,
@@ -1530,8 +1549,9 @@ parse (char       **xml_files,
       for (l = generated_files; l != NULL; l = l->next)
         {
           const gchar *file_name = l->data;
-          g_print ("%s\n", file_name);
+          g_print ("%s ", file_name);
         }
+      g_print ("\n");
       if (!file_print_func_end (TRUE, error))
         {
           goto out;
diff --git a/src/eggdbus/interface.c b/src/eggdbus/interface.c
index 2e74c4d..2a7bfd8 100644
--- a/src/eggdbus/interface.c
+++ b/src/eggdbus/interface.c
@@ -3280,3 +3280,583 @@ interface_generate_iface_c_file (const EggDBusInterfaceInfo  *interface,
 
   return ret;
 }
+
+static void
+docbook_get_typename_for_signature (const gchar   *signature,
+                                    gchar        **out_name,
+                                    gchar        **out_link)
+{
+  if (out_name != NULL)
+    *out_name = g_strdup_printf ("'%s'", signature);
+
+  if (out_link != NULL)
+    *out_link = g_strdup_printf ("'%s'", signature);
+}
+
+static void
+docbook_print_arg (const EggDBusInterfaceArgInfo  *arg,
+                   const gchar                    *arg_prefix,
+                   guint                           arg_max_len)
+{
+  gchar *arg_type_name;
+  gchar *arg_type_link;
+
+  docbook_get_typename_for_signature (arg->signature, &arg_type_name, &arg_type_link);
+
+  g_print ("%s%s%*s%s",
+           arg_prefix,
+           arg_type_link,
+           (int) (arg_max_len - strlen (arg_type_name)), "",
+           arg->name);
+
+  g_free (arg_type_name);
+  g_free (arg_type_link);
+}
+
+static guint
+docbook_get_max_arg_len_for_method (const EggDBusInterfaceMethodInfo    *method)
+{
+  guint n;
+  guint max_arg_len;
+
+  max_arg_len = 0;
+
+  for (n = 0; n < method->in_num_args; n++)
+    {
+      const EggDBusInterfaceArgInfo *arg = method->in_args + n;
+      gchar *arg_type_name;
+      guint arg_len;
+
+      docbook_get_typename_for_signature (arg->signature, &arg_type_name, NULL);
+      arg_len = strlen (arg_type_name);
+      g_free (arg_type_name);
+
+      if (arg_len > max_arg_len)
+        max_arg_len = arg_len;
+    }
+
+  for (n = 0; n < method->out_num_args; n++)
+    {
+      const EggDBusInterfaceArgInfo *arg = method->out_args + n;
+      gchar *arg_type_name;
+      guint arg_len;
+
+      docbook_get_typename_for_signature (arg->signature, &arg_type_name, NULL);
+      arg_len = strlen (arg_type_name);
+      g_free (arg_type_name);
+
+      if (arg_len > max_arg_len)
+        max_arg_len = arg_len;
+    }
+
+  return max_arg_len;
+}
+
+static guint
+docbook_get_max_arg_len_for_signal (const EggDBusInterfaceSignalInfo *signal)
+{
+  guint n;
+  guint max_arg_len;
+
+  max_arg_len = 0;
+
+  for (n = 0; n < signal->num_args; n++)
+    {
+      const EggDBusInterfaceArgInfo *arg = signal->args + n;
+      gchar *arg_type_name;
+      guint arg_len;
+
+      docbook_get_typename_for_signature (arg->signature, &arg_type_name, NULL);
+      arg_len = strlen (arg_type_name);
+      g_free (arg_type_name);
+
+      if (arg_len > max_arg_len)
+        max_arg_len = arg_len;
+    }
+
+  return max_arg_len;
+}
+
+static void
+docbook_print_method_prototype (const EggDBusInterfaceInfo          *interface,
+                                const EggDBusInterfaceMethodInfo    *method,
+                                guint                                indent,
+                                guint                                arg_max_len,
+                                gboolean                             use_hyperlink)
+{
+  guint n;
+  guint num_printed;
+  guint first_indent;
+
+  first_indent = indent - strlen (method->name) - 1;
+
+  if (use_hyperlink)
+    {
+      g_print ("<link linkend=\"%s.%s\">%s</link>%*s(",
+               interface->name,
+               method->name,
+               method->name,
+               first_indent, "");
+    }
+  else
+    {
+      g_print ("%s%*s(",
+               method->name,
+               first_indent, "");
+    }
+
+  num_printed = 0;
+  for (n = 0; n < method->in_num_args; n++)
+    {
+      const EggDBusInterfaceArgInfo *arg = method->in_args + n;
+
+      if (num_printed != 0)
+        g_print (",\n%*s", indent, "");
+
+      docbook_print_arg (arg, "in  ", arg_max_len);
+
+      num_printed++;
+    }
+
+  for (n = 0; n < method->out_num_args; n++)
+    {
+      const EggDBusInterfaceArgInfo *arg = method->out_args + n;
+
+      if (num_printed != 0)
+        g_print (",\n%*s", indent, "");
+
+      docbook_print_arg (arg, "out ", arg_max_len);
+
+      num_printed++;
+    }
+
+  g_print (")\n");
+}
+
+static void
+docbook_print_signal_prototype (const EggDBusInterfaceInfo          *interface,
+                                const EggDBusInterfaceSignalInfo    *signal,
+                                guint                                indent,
+                                guint                                arg_max_len,
+                                gboolean                             use_hyperlink)
+{
+  guint n;
+  guint num_printed;
+  guint first_indent;
+
+  first_indent = indent - strlen (signal->name) - 1;
+
+  if (use_hyperlink)
+    {
+      g_print ("<link linkend=\"%s::%s\">%s</link>%*s(",
+               interface->name,
+               signal->name,
+               signal->name,
+               first_indent, "");
+    }
+  else
+    {
+      g_print ("%s%*s(",
+               signal->name,
+               first_indent, "");
+    }
+
+  num_printed = 0;
+  for (n = 0; n < signal->num_args; n++)
+    {
+      const EggDBusInterfaceArgInfo *arg = signal->args + n;
+
+      if (num_printed != 0)
+        g_print (",\n%*s", indent, "");
+
+      docbook_print_arg (arg, "", arg_max_len);
+
+      num_printed++;
+    }
+
+  g_print (")\n");
+}
+
+static void
+docbook_print_property_prototype (const EggDBusInterfaceInfo          *interface,
+                                  const EggDBusInterfacePropertyInfo  *property,
+                                  guint                                indent,
+                                  gboolean                             use_hyperlink)
+{
+  guint first_indent;
+  gchar *arg_type_link;
+
+  first_indent = indent - strlen (property->name) - 1;
+
+  if (use_hyperlink)
+    {
+      g_print ("<link linkend=\"%s:%s\">%s</link>%*s    ",
+               interface->name,
+               property->name,
+               property->name,
+               first_indent, "");
+    }
+  else
+    {
+      g_print ("%s%*s    ",
+               property->name,
+               first_indent, "");
+    }
+
+  if ((property->flags & EGG_DBUS_INTERFACE_PROPERTY_INFO_FLAGS_READABLE) &&
+      (property->flags & EGG_DBUS_INTERFACE_PROPERTY_INFO_FLAGS_WRITABLE))
+    {
+      g_print ("readwrite ");
+    }
+  else if (property->flags & EGG_DBUS_INTERFACE_PROPERTY_INFO_FLAGS_READABLE)
+    {
+      g_print ("readable  ");
+    }
+  else if (property->flags & EGG_DBUS_INTERFACE_PROPERTY_INFO_FLAGS_WRITABLE)
+    {
+      g_print ("writable  ");
+    }
+  else
+    {
+      g_print ("          ");
+    }
+
+  docbook_get_typename_for_signature (property->signature, NULL, &arg_type_link);
+
+  g_print ("   %s\n", arg_type_link);
+
+  g_free (arg_type_link);
+}
+
+static void
+docbook_print_arg_in_list (const gchar                   *prefix,
+                           const EggDBusInterfaceArgInfo *arg)
+{
+  gchar *arg_doc_string;
+
+  arg_doc_string = get_doc_string (arg->annotations, "Argument");
+
+  g_print ("  <varlistentry>\n");
+  g_print ("    <term>%s<parameter>%s</parameter>:</term>\n", prefix, arg->name);
+  g_print ("    <listitem>\n");
+  g_print ("      <para>\n");
+  g_print ("%s\n", arg_doc_string);
+  g_print ("      </para>\n");
+  g_print ("    </listitem>\n");
+  g_print ("  </varlistentry>\n");
+
+  g_free (arg_doc_string);
+}
+
+static void
+docbook_print_args (const EggDBusInterfaceInfo     *interface,
+                    const gchar                    *prefix0,
+                    const EggDBusInterfaceArgInfo  *args0,
+                    guint                           num_args0,
+                    const gchar                    *prefix1,
+                    const EggDBusInterfaceArgInfo  *args1,
+                    guint                           num_args1)
+{
+  guint n;
+
+  g_print ("<variablelist role=\"params\">\n");
+
+  for (n = 0; n < num_args0; n++)
+    {
+      const EggDBusInterfaceArgInfo *arg = args0 + n;
+      docbook_print_arg_in_list (prefix0, arg);
+    }
+
+  for (n = 0; n < num_args1; n++)
+    {
+      const EggDBusInterfaceArgInfo *arg = args1 + n;
+      docbook_print_arg_in_list (prefix1, arg);
+    }
+
+  g_print ("</variablelist>\n");
+}
+
+gboolean
+interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
+                            GError                     **error)
+{
+  gboolean ret;
+  gchar *interface_summary_doc_string;
+  gchar *interface_doc_string;
+  guint n;
+  guint indent;
+  guint arg_max_len_for_all;
+
+  ret = FALSE;
+
+  interface_summary_doc_string = get_summary_doc_string (interface->annotations, "Interface");
+  interface_doc_string = get_doc_string (interface->annotations, "Interface");
+
+  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 ("  <refmeta>\n");
+  g_print ("    <refentrytitle role=\"top_of_page\">%s</refentrytitle>\n", interface->name);
+  g_print ("  </refmeta>\n");
+  g_print ("  <refnamediv>\n");
+  g_print ("    <refname>%s</refname>\n", interface->name);
+  g_print ("    <refpurpose>%s</refpurpose>\n", interface_summary_doc_string);
+  g_print ("  </refnamediv>\n");
+
+  /* Synopsis for methods */
+  if (interface->num_methods > 0)
+    {
+      g_print ("  <refsynopsisdiv role=\"synopsis\">\n");
+      g_print ("    <title role=\"synopsis.title\">Methods</title>\n");
+      g_print ("    <synopsis>\n");
+      indent = 0;
+      arg_max_len_for_all = 0;
+      for (n = 0; n < interface->num_methods; n++)
+        {
+          const EggDBusInterfaceMethodInfo *method = interface->methods + n;
+          guint method_name_len;
+          guint arg_max_len;
+
+          method_name_len = strlen (method->name);
+          if (method_name_len > indent)
+            indent = method_name_len;
+
+          arg_max_len = docbook_get_max_arg_len_for_method (method);
+          if (arg_max_len > arg_max_len_for_all)
+            arg_max_len_for_all = arg_max_len;
+        }
+      for (n = 0; n < interface->num_methods; n++)
+        {
+          const EggDBusInterfaceMethodInfo *method = interface->methods + n;
+
+          docbook_print_method_prototype (interface,
+                                          method,
+                                          indent + 2,
+                                          arg_max_len_for_all + 2,
+                                          TRUE);
+        }
+      g_print ("    </synopsis>\n");
+      g_print ("  </refsynopsisdiv>\n");
+    }
+
+  /* Synopsis for signals */
+  if (interface->num_signals > 0)
+    {
+      g_print ("  <refsect1 role=\"signal_proto\">\n");
+      g_print ("    <title role=\"signal_proto.title\">Signals</title>\n");
+      g_print ("    <synopsis>\n");
+      indent = 0;
+      arg_max_len_for_all = 0;
+      for (n = 0; n < interface->num_signals; n++)
+        {
+          const EggDBusInterfaceSignalInfo *signal = interface->signals + n;
+          guint signal_name_len;
+          guint arg_max_len;
+
+          signal_name_len = strlen (signal->name);
+          if (signal_name_len > indent)
+            indent = signal_name_len;
+
+          arg_max_len = docbook_get_max_arg_len_for_signal (signal);
+          if (arg_max_len > arg_max_len_for_all)
+            arg_max_len_for_all = arg_max_len;
+        }
+      for (n = 0; n < interface->num_signals; n++)
+        {
+          const EggDBusInterfaceSignalInfo *signal = interface->signals + n;
+
+          docbook_print_signal_prototype (interface,
+                                          signal,
+                                          indent + 2,
+                                          arg_max_len_for_all + 2,
+                                          TRUE);
+        }
+      g_print ("    </synopsis>\n");
+      g_print ("  </refsect1>\n");
+    }
+
+  /* Synopsis for properties */
+  if (interface->num_properties > 0)
+    {
+      g_print ("  <refsect1 role=\"properties\">\n");
+      g_print ("    <title role=\"properties.title\">Properties</title>\n");
+      g_print ("    <synopsis>\n");
+      indent = 0;
+      arg_max_len_for_all = 0;
+      for (n = 0; n < interface->num_properties; n++)
+        {
+          const EggDBusInterfacePropertyInfo *property = interface->properties + n;
+          guint property_name_len;
+
+          property_name_len = strlen (property->name);
+          if (property_name_len > indent)
+            indent = property_name_len;
+        }
+      for (n = 0; n < interface->num_properties; n++)
+        {
+          const EggDBusInterfacePropertyInfo *property = interface->properties + n;
+
+          docbook_print_property_prototype (interface,
+                                            property,
+                                            indent + 2,
+                                            TRUE);
+        }
+      g_print ("    </synopsis>\n");
+      g_print ("  </refsect1>\n");
+    }
+
+  /* Description */
+  g_print ("  <refsect1 role=\"desc\">\n");
+  g_print ("    <title role=\"desc.title\">Description</title>\n");
+  g_print ("      <para>\n");
+  g_print ("%s\n", interface_doc_string);
+  g_print ("      </para>\n");
+  g_print ("  </refsect1>\n");
+
+  /* Details for each method */
+  if (interface->num_methods > 0)
+    {
+      g_print ("  <refsect1 role=\"details\">\n");
+      g_print ("    <title role=\"details.title\">Method Details</title>\n");
+      for (n = 0; n < interface->num_methods; n++)
+        {
+          const EggDBusInterfaceMethodInfo *method = interface->methods + n;
+          guint method_name_len;
+          guint arg_max_len;
+          gchar *doc_string;
+
+          method_name_len = strlen (method->name);
+
+          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",
+                   interface->name,
+                   method->name,
+                   method->name);
+          g_print ("    <programlisting>\n");
+
+          docbook_print_method_prototype (interface,
+                                          method,
+                                          method_name_len + 2,
+                                          arg_max_len + 2,
+                                          FALSE);
+
+          g_print ("    </programlisting>\n");
+          g_print ("    <para>\n");
+          doc_string = get_doc_string (method->annotations, "Method");
+          g_print ("%s\n", doc_string);
+          g_free (doc_string);
+          g_print ("    </para>\n");
+
+          docbook_print_args (interface,
+                              "in ",
+                              method->in_args,
+                              method->in_num_args,
+                              "out ",
+                              method->out_args,
+                              method->out_num_args);
+
+          g_print ("    </refsect2>\n");
+        }
+      g_print ("  </refsect1>\n");
+    }
+
+  /* Details for each signal */
+  if (interface->num_signals > 0)
+    {
+      g_print ("  <refsect1 role=\"signals\">\n");
+      g_print ("    <title role=\"signals.title\">Signal Details</title>\n");
+      for (n = 0; n < interface->num_signals; n++)
+        {
+          const EggDBusInterfaceSignalInfo *signal = interface->signals + n;
+          guint signal_name_len;
+          guint arg_max_len;
+          gchar *doc_string;
+
+          signal_name_len = strlen (signal->name);
+
+          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",
+                   interface->name,
+                   signal->name,
+                   signal->name);
+          g_print ("    <programlisting>\n");
+
+          docbook_print_signal_prototype (interface,
+                                          signal,
+                                          signal_name_len + 2,
+                                          arg_max_len + 2,
+                                          FALSE);
+
+          g_print ("    </programlisting>\n");
+          g_print ("    <para>\n");
+          doc_string = get_doc_string (signal->annotations, "Signal");
+          g_print ("%s\n", doc_string);
+          g_free (doc_string);
+          g_print ("    </para>\n");
+
+          docbook_print_args (interface,
+                              "",
+                              signal->args,
+                              signal->num_args,
+                              NULL,
+                              NULL,
+                              0);
+
+          g_print ("    </refsect2>\n");
+        }
+      g_print ("  </refsect1>\n");
+    }
+
+  /* Details for each property */
+  if (interface->num_properties > 0)
+    {
+      g_print ("  <refsect1 role=\"property_details\">\n");
+      g_print ("    <title role=\"property_details.title\">Property Details</title>\n");
+      for (n = 0; n < interface->num_properties; n++)
+        {
+          const EggDBusInterfacePropertyInfo *property = interface->properties + n;
+          guint property_name_len;
+          gchar *doc_string;
+
+          property_name_len = strlen (property->name);
+
+          g_print ("    <refsect2>\n");
+          g_print ("      <title><anchor role=\"function\" id=\"%s:%s\"/>The \"%s\" property</title>\n",
+                   interface->name,
+                   property->name,
+                   property->name);
+          g_print ("    <programlisting>\n");
+
+          docbook_print_property_prototype (interface,
+                                            property,
+                                            property_name_len + 2,
+                                            FALSE);
+
+          g_print ("    </programlisting>\n");
+          g_print ("    <para>\n");
+          doc_string = get_doc_string (property->annotations, "Property");
+          g_print ("%s\n", doc_string);
+          g_free (doc_string);
+          g_print ("    </para>\n");
+
+          g_print ("    </refsect2>\n");
+        }
+      g_print ("  </refsect1>\n");
+    }
+
+  g_print ("</refentry>\n");
+
+  ret = TRUE;
+
+  g_free (interface_summary_doc_string);
+  g_free (interface_doc_string);
+
+  return ret;
+}
+
diff --git a/src/eggdbus/interface.h b/src/eggdbus/interface.h
index eecb35d..d5e3794 100644
--- a/src/eggdbus/interface.h
+++ b/src/eggdbus/interface.h
@@ -39,6 +39,9 @@ gboolean interface_generate_iface_c_file (const EggDBusInterfaceInfo  *interface
                                           const char                  *h_file_name,
                                           GError                     **error);
 
+gboolean interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
+                                     GError                     **error);
+
 G_END_DECLS
 
 #endif /* __INTERFACE_H */
diff --git a/src/tests/Makefile.am b/src/tests/Makefile.am
index 964ec24..56f9a91 100644
--- a/src/tests/Makefile.am
+++ b/src/tests/Makefile.am
@@ -35,46 +35,9 @@ test-built-sources.stamp : Makefile.am $(top_builddir)/src/eggdbus/eggdbus-bindi
 	  --stamp-file test-built-sources.stamp									\
 	  $(NULL)
 
-# keep in sync with contents of test-built-sources.stamp
+# keep in sync with contents of test-built-sources.stamp (Thanks autotools)
 #
-test_built_sources = 				\
-	testbindingsmarshal.c			\
-	testbindingsmarshal.h			\
-	testbindingsmarshal.list		\
-	testbindings.c				\
-	testbindings.h				\
-	testbindingstypes.h			\
-	testtwiddle.c				\
-	testtwiddle.h				\
-	testtweak.c				\
-	testtweak.h				\
-	testfrob.c				\
-	testfrob.h				\
-	testvehicle.c				\
-	testvehicle.h				\
-	testotherflags.c			\
-	testotherflags.h			\
-	testdeleteflags.c			\
-	testdeleteflags.h			\
-	testcreateflags.c			\
-	testcreateflags.h			\
-	testdetailederror.c			\
-	testdetailederror.h			\
-	testerror.c				\
-	testerror.h				\
-	teststructwithvariant.c			\
-	teststructwithvariant.h			\
-	testextendeddescribedpoint.c		\
-	testextendeddescribedpoint.h		\
-	testdescribedpair.c			\
-	testdescribedpair.h			\
-	testdescribedpoint.c			\
-	testdescribedpoint.h			\
-	testpair.c				\
-	testpair.h				\
-	testpoint.c				\
-	testpoint.h				\
-	$(NULL)
+test_built_sources = testbindingsmarshal.c testbindingsmarshal.h testbindingsmarshal.list testbindings.c testbindings.h testbindingstypes.h testtwiddle.c testtwiddle.h docbook-interface-com.example.Twiddle.xml testtweak.c testtweak.h docbook-interface-com.example.Tweak.xml testfrob.c testfrob.h docbook-interface-com.example.Frob.xml testvehicle.c testvehicle.h testotherflags.c testotherflags.h testdeleteflags.c testdeleteflags.h testcreateflags.c testcreateflags.h testdetailederror.c testdetailederror.h testerror.c testerror.h teststructwithvariant.c teststructwithvariant.h testextendeddescribedpoint.c testextendeddescribedpoint.h testdescribedpair.c testdescribedpair.h testdescribedpoint.c testdescribedpoint.h testpair.c testpair.h testpoint.c testpoint.h
 
 libeggdbustests_la_SOURCES = 				\
 	test-built-sources.stamp			\