generate Docbook docs for enumerations, flags and error domains

8 files changed, 248 insertions, 4 deletions

diff --git a/docs/eggdbus/Makefile.am b/docs/eggdbus/Makefile.am
index e6b3b37..940f55c 100644
--- a/docs/eggdbus/Makefile.am
+++ b/docs/eggdbus/Makefile.am
@@ -59,10 +59,20 @@ MKTMPL_OPTIONS=
 content_files =  			    						\
 	../version.xml			    						\
 	../man/eggdbus-binding-tool.xml	    						\
+	../../src/eggdbus/docbook-enum-ReleaseNameReply.xml				\
+	../../src/eggdbus/docbook-enum-RequestNameFlags.xml				\
+	../../src/eggdbus/docbook-enum-RequestNameReply.xml				\
+	../../src/eggdbus/docbook-enum-StartServiceByNameReply.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-enum-CreateFlags.xml					\
+	../../src/tests/docbook-enum-DeleteFlags.xml					\
+	../../src/tests/docbook-enum-DetailedError.xml					\
+	../../src/tests/docbook-enum-Error.xml						\
+	../../src/tests/docbook-enum-OtherFlags.xml					\
+	../../src/tests/docbook-enum-Vehicle.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			\
diff --git a/docs/eggdbus/eggdbus-docs.xml b/docs/eggdbus/eggdbus-docs.xml
index 3bf5323..bd4b688 100644
--- a/docs/eggdbus/eggdbus-docs.xml
+++ b/docs/eggdbus/eggdbus-docs.xml
@@ -131,10 +131,20 @@
 
     <chapter id="example-dbus">
       <title>Example of Generated D-Bus docs</title>
+      <xi:include href="../../src/eggdbus/docbook-enum-ReleaseNameReply.xml"/>
+      <xi:include href="../../src/eggdbus/docbook-enum-RequestNameFlags.xml"/>
+      <xi:include href="../../src/eggdbus/docbook-enum-RequestNameReply.xml"/>
+      <xi:include href="../../src/eggdbus/docbook-enum-StartServiceByNameReply.xml"/>
       <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-enum-CreateFlags.xml"/>
+      <xi:include href="../../src/tests/docbook-enum-DeleteFlags.xml"/>
+      <xi:include href="../../src/tests/docbook-enum-DetailedError.xml"/>
+      <xi:include href="../../src/tests/docbook-enum-Error.xml"/>
+      <xi:include href="../../src/tests/docbook-enum-OtherFlags.xml"/>
+      <xi:include href="../../src/tests/docbook-enum-Vehicle.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"/>
diff --git a/src/eggdbus/Makefile.am b/src/eggdbus/Makefile.am
index b0c7f2e..c7b11cd 100644
--- a/src/eggdbus/Makefile.am
+++ b/src/eggdbus/Makefile.am
@@ -150,7 +150,7 @@ eggdbus-built-sources.stamp : eggdbus-binding-tool Makefile.am org.freedesktop.D
 
 # 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 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
+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 docbook-enum-StartServiceByNameReply.xml eggdbusreleasenamereply.c eggdbusreleasenamereply.h docbook-enum-ReleaseNameReply.xml eggdbusrequestnamereply.c eggdbusrequestnamereply.h docbook-enum-RequestNameReply.xml eggdbusrequestnameflags.c eggdbusrequestnameflags.h docbook-enum-RequestNameFlags.xml
 
 enum_headers =                        					\
 	eggdbusinterface.h						\
diff --git a/src/eggdbus/docbook.c b/src/eggdbus/docbook.c
index 888834d..37eafa5 100644
--- a/src/eggdbus/docbook.c
+++ b/src/eggdbus/docbook.c
@@ -799,3 +799,205 @@ interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
 
   return ret;
 }
+
+/* ---------------------------------------------------------------------------------------------------- */
+
+gboolean
+enum_generate_docbook (EnumData  *enum_data,
+                       GError   **error)
+{
+  gboolean ret;
+  gchar *enum_summary_doc_string;
+  gchar *enum_doc_string;
+  const gchar *type_string;
+  guint n;
+  guint len;
+  guint max_len;
+  guint m;
+
+  ret = FALSE;
+
+  switch (enum_data->type)
+    {
+    case ENUM_DATA_TYPE_ERROR_DOMAIN:
+      type_string = "Error Domain";
+      break;
+
+    case ENUM_DATA_TYPE_FLAGS:
+      type_string = "Flags";
+      break;
+
+    case ENUM_DATA_TYPE_ENUM:
+      type_string = "Enumeration";
+      break;
+
+    default:
+      g_assert_not_reached ();
+      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);
+
+  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", enum_data->name);
+  g_print ("  <refmeta>\n");
+  g_print ("    <refentrytitle role=\"top_of_page\">%s</refentrytitle>\n", enum_data->name);
+  g_print ("  </refmeta>\n");
+  g_print ("  <refnamediv>\n");
+  g_print ("    <refname>%s</refname>\n", enum_data->name);
+  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",
+               enum_data->maximal_dbus_prefix,
+               enum_data->maximal_dbus_prefix);
+    }
+  else
+    {
+      g_print ("      <title><anchor role=\"enum\" id=\"%s\"/>The %s %s</title>\n",
+               enum_data->name,
+               enum_data->name,
+               type_string);
+    }
+  g_print ("        <para>\n");
+  g_print ("          <programlisting>\n");
+  switch (enum_data->type)
+    {
+    case ENUM_DATA_TYPE_ERROR_DOMAIN:
+      g_print ("{\n");
+      for (n = 0; n < enum_data->num_elements; n++)
+        {
+          EnumElemData *elem = enum_data->elements[n];
+
+          if (n != 0)
+            g_print (",\n");
+
+          g_print ("  %s", elem->name);
+        }
+      g_print ("\n"
+               "}\n");
+      break;
+
+    case ENUM_DATA_TYPE_FLAGS:
+      max_len = 0;
+      for (n = 0; n < enum_data->num_elements; n++)
+        {
+          EnumElemData *elem = enum_data->elements[n];
+          len = strlen (elem->name);
+          if (len > max_len)
+            max_len = len;
+        }
+
+      g_print ("{\n");
+      m = 1;
+      for (n = 0; n < enum_data->num_elements; n++)
+        {
+          EnumElemData *elem = enum_data->elements[n];
+          if (n != 0)
+            g_print (",\n");
+
+          if (elem->value != -1)
+            m = elem->value;
+
+          len = strlen (elem->name);
+          g_print ("  %s %*s= 0x%08x", elem->name, max_len - len, "", m);
+
+          m *= 2;
+        }
+      g_print ("\n"
+               "}\n");
+      break;
+
+    case ENUM_DATA_TYPE_ENUM:
+      max_len = 0;
+      for (n = 0; n < enum_data->num_elements; n++)
+        {
+          EnumElemData *elem = enum_data->elements[n];
+          len = strlen (elem->name);
+          if (len > max_len)
+            max_len = len;
+        }
+
+      g_print ("{\n");
+      m = 0;
+      for (n = 0; n < enum_data->num_elements; n++)
+        {
+          EnumElemData *elem = enum_data->elements[n];
+          if (n != 0)
+            g_print (",\n");
+
+          if (elem->value != -1)
+            m = elem->value;
+
+          len = strlen (elem->name);
+          g_print ("  %s %*s= %d", elem->name, max_len - len, "", m);
+
+          m++;
+        }
+      g_print ("\n"
+               "}\n");
+      break;
+    }
+  g_print ("          </programlisting>\n");
+  g_print ("          <para>\n");
+  g_print ("%s\n", enum_doc_string);
+  g_print ("          </para>\n");
+
+  g_print ("          <variablelist role=\"constant\">\n");
+  for (n = 0; n < enum_data->num_elements; n++)
+    {
+      EnumElemData *elem = enum_data->elements[n];
+      gchar *enum_doc_string;
+
+      enum_doc_string = get_doc_string (elem->annotations, "Enum");
+
+      switch (enum_data->type)
+        {
+        case ENUM_DATA_TYPE_ERROR_DOMAIN:
+          g_print ("  <varlistentry id=\"constant-%s\" role=\"constant\">\n", elem->name);
+          break;
+
+        case ENUM_DATA_TYPE_FLAGS:
+          g_print ("  <varlistentry id=\"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);
+          break;
+        }
+      g_print ("    <term><literal>%s</literal></term>\n", elem->name);
+      g_print ("    <listitem>\n");
+      g_print ("      <para>\n");
+      g_print ("%s\n", enum_doc_string);
+      g_print ("      </para>\n");
+      g_print ("    </listitem>\n");
+      g_print ("  </varlistentry>\n");
+
+      g_free (enum_doc_string);
+    }
+  g_print ("          </variablelist>\n");
+  g_print ("        </para>\n");
+  g_print ("    </refsect2>\n");
+
+  g_print ("  </refsect1>\n");
+
+
+  g_print ("</refentry>\n");
+
+  ret = TRUE;
+
+  g_free (enum_doc_string);
+  g_free (enum_summary_doc_string);
+
+  return ret;
+}
+
diff --git a/src/eggdbus/docbook.h b/src/eggdbus/docbook.h
index 8f68fca..3e141cb 100644
--- a/src/eggdbus/docbook.h
+++ b/src/eggdbus/docbook.h
@@ -23,12 +23,16 @@
 #define __DOCBOOK_H
 
 #include "eggdbusinterface.h"
+#include "enum.h"
 
 G_BEGIN_DECLS
 
 gboolean interface_generate_docbook (const EggDBusInterfaceInfo  *interface,
                                      GError                     **error);
 
+gboolean enum_generate_docbook (EnumData  *enum_data,
+                                GError   **error);
+
 G_END_DECLS
 
 #endif /* __DOCBOOK_H */
diff --git a/src/eggdbus/eggdbusbindingtool.c b/src/eggdbus/eggdbusbindingtool.c
index 740fbb8..b29f924 100644
--- a/src/eggdbus/eggdbusbindingtool.c
+++ b/src/eggdbus/eggdbusbindingtool.c
@@ -1141,9 +1141,27 @@ generate_enums (GSList   *nodes,
             {
               gchar *h_file_name;
               gchar *c_file_name;
+              gchar *docbook_file_name;
 
+              /* now generate Docbook, H and C files for enum_data */
 
-              /* now generate C and H 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))
+                {
+                  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);
 
               /* generate header file */
               h_file_name = compute_file_name (name_space, enum_data->name, ".h");
diff --git a/src/tests/Makefile.am b/src/tests/Makefile.am
index 56f9a91..bea8866 100644
--- a/src/tests/Makefile.am
+++ b/src/tests/Makefile.am
@@ -37,7 +37,7 @@ test-built-sources.stamp : Makefile.am $(top_builddir)/src/eggdbus/eggdbus-bindi
 
 # 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 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
+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 docbook-enum-Vehicle.xml testotherflags.c testotherflags.h docbook-enum-OtherFlags.xml testdeleteflags.c testdeleteflags.h docbook-enum-DeleteFlags.xml testcreateflags.c testcreateflags.h docbook-enum-CreateFlags.xml testdetailederror.c testdetailederror.h docbook-enum-DetailedError.xml testerror.c testerror.h docbook-enum-Error.xml 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			\
diff --git a/src/tests/com.example.Twiddle.xml b/src/tests/com.example.Twiddle.xml
index ea568eb..743b682 100644
--- a/src/tests/com.example.Twiddle.xml
+++ b/src/tests/com.example.Twiddle.xml
@@ -51,7 +51,7 @@
       <!-- docstring explicitly left out -->
     </annotation>
     <annotation name="org.gtk.EggDBus.Flags.Member" value="YetAnotherFlag">
-      <annotation name="org.gtk.EggDBus.DocString" value="This should have value 0x100 == 256 == (1<<8)"/>
+      <annotation name="org.gtk.EggDBus.DocString" value="This should have value 0x100 == 256"/>
     </annotation>
   </annotation>