Merge branch 'split-codegen-doc'

Reviwed-by: Travis Reitter <travis.reitter@collabora.co.uk>

6 files changed, 370 insertions, 259 deletions

diff --git a/tools/c-constants-gen.py b/tools/c-constants-gen.py
index 8969ffdca..09608c2bd 100644
--- a/tools/c-constants-gen.py
+++ b/tools/c-constants-gen.py
@@ -7,17 +7,23 @@ from libglibcodegen import NS_TP, get_docstring, \
         get_descendant_text, get_by_path
 
 class Generator(object):
-    def __init__(self, prefix, dom):
+    def __init__(self, prefix, dom, output_base):
         self.prefix = prefix + '_'
         self.spec = get_by_path(dom, "spec")[0]
 
+        self.__header = open(output_base + '.h', 'w')
+        self.__docs = open(output_base + '-gtk-doc.h', 'w')
+
     def __call__(self):
         self.do_header()
         self.do_body()
         self.do_footer()
 
     def write(self, code):
-        stdout.write(code.encode('utf-8'))
+        self.__header.write(code.encode('utf-8'))
+
+    def d(self, code):
+        self.__docs.write(code.encode('utf-8'))
 
     # Header
     def do_header(self):
@@ -54,25 +60,27 @@ extern "C" {
         value_prefix = flags.getAttribute('singular') or \
                        flags.getAttribute('value-prefix') or \
                        flags.getAttribute('name')
-        self.write("""\
+        self.d("""\
 /**
  *
 %s:
 """ % (self.prefix + name).replace('_', ''))
         for flag in get_by_path(flags, 'flag'):
             self.do_gtkdoc(flag, value_prefix)
-        self.write(' *\n')
+        self.d(' *\n')
         docstrings = get_by_path(flags, 'docstring')
         if docstrings:
-            self.write("""\
+            self.d("""\
  * <![CDATA[%s]]>
  *
 """ % get_descendant_text(docstrings).replace('\n', ' '))
-        self.write("""\
+        self.d("""\
  * Bitfield/set of flags generated from the Telepathy specification.
  */
-typedef enum {
 """)
+
+        self.write("typedef enum {\n")
+
         for flag in get_by_path(flags, 'flag'):
             self.do_val(flag, value_prefix)
         self.write("""\
@@ -87,7 +95,7 @@ typedef enum {
                        enum.getAttribute('name')
         name_plural = enum.getAttribute('plural') or \
                       enum.getAttribute('name') + 's'
-        self.write("""\
+        self.d("""\
 /**
  *
 %s:
@@ -95,28 +103,35 @@ typedef enum {
         vals = get_by_path(enum, 'enumvalue')
         for val in vals:
             self.do_gtkdoc(val, value_prefix)
-        self.write(' *\n')
+        self.d(' *\n')
         docstrings = get_by_path(enum, 'docstring')
         if docstrings:
-            self.write("""\
+            self.d("""\
  * <![CDATA[%s]]>
  *
 """ % get_descendant_text(docstrings).replace('\n', ' '))
-        self.write("""\
+        self.d("""\
  * Bitfield/set of flags generated from the Telepathy specification.
  */
-typedef enum {
 """)
+
+        self.write("typedef enum {\n")
+
         for val in vals:
             self.do_val(val, value_prefix)
-        self.write("""\
-} %(mixed-name)s;
+        self.write("} %s;\n" % (self.prefix + name).replace('_', ''))
 
+        self.d("""\
 /**
  * NUM_%(upper-plural)s:
  *
  * 1 higher than the highest valid value of #%(mixed-name)s.
  */
+""" % {'mixed-name' : (self.prefix + name).replace('_', ''),
+       'upper-plural' : (self.prefix + name_plural).upper(),
+       'last-val' : vals[-1].getAttribute('value')})
+
+        self.write("""\
 #define NUM_%(upper-plural)s (%(last-val)s+1)
 
 """ % {'mixed-name' : (self.prefix + name).replace('_', ''),
@@ -133,13 +148,13 @@ typedef enum {
         self.write('    %s = %s,\n' % (use_name, val.getAttribute('value')))
 
     def do_gtkdoc(self, node, value_prefix):
-        self.write(' * @')
-        self.write((self.prefix + value_prefix + '_' +
+        self.d(' * @')
+        self.d((self.prefix + value_prefix + '_' +
             node.getAttribute('suffix')).upper())
-        self.write(': <![CDATA[')
+        self.d(': <![CDATA[')
         docstring = get_by_path(node, 'docstring')
-        self.write(get_descendant_text(docstring).replace('\n', ' '))
-        self.write(']]>\n')
+        self.d(get_descendant_text(docstring).replace('\n', ' '))
+        self.d(']]>\n')
 
     # Footer
     def do_footer(self):
@@ -151,4 +166,4 @@ typedef enum {
 
 if __name__ == '__main__':
     argv = argv[1:]
-    Generator(argv[0], xml.dom.minidom.parse(argv[1]))()
+    Generator(argv[0], xml.dom.minidom.parse(argv[1]), argv[2])()
diff --git a/tools/glib-client-gen.py b/tools/glib-client-gen.py
index 5263672e3..6b0bdeba1 100644
--- a/tools/glib-client-gen.py
+++ b/tools/glib-client-gen.py
@@ -39,6 +39,7 @@ class Generator(object):
         self.dom = dom
         self.__header = []
         self.__body = []
+        self.__docs = []
 
         self.prefix_lc = prefix.lower()
         self.prefix_uc = prefix.upper()
@@ -71,6 +72,11 @@ class Generator(object):
             s = s.encode('utf-8')
         self.__body.append(s)
 
+    def d(self, s):
+        if isinstance(s, unicode):
+            s = s.encode('utf-8')
+        self.__docs.append(s)
+
     def get_iface_quark(self):
         assert self.iface_dbus is not None
         assert self.iface_uc is not None
@@ -123,25 +129,27 @@ class Generator(object):
         #   guint arg_handle, gboolean arg_suppress_handler,
         #   gpointer user_data, GObject *weak_object);
 
-        self.b('/**')
-        self.b(' * %s:' % callback_name)
-        self.b(' * @proxy: The proxy on which %s_%s_connect_to_%s ()'
+        self.d('/**')
+        self.d(' * %s:' % callback_name)
+        self.d(' * @proxy: The proxy on which %s_%s_connect_to_%s ()'
                % (self.prefix_lc, iface_lc, member_lc))
-        self.b(' *  was called')
+        self.d(' *  was called')
 
         for arg in args:
             name, info, tp_type, elt = arg
             ctype, gtype, marshaller, pointer = info
 
-            self.b(' * @%s: %s' % (name,
+            self.d(' * @%s: %s' % (name,
                 xml_escape(get_docstring(elt) or '(Undocumented)')))
 
-        self.b(' * @user_data: User-supplied data')
-        self.b(' * @weak_object: User-supplied weakly referenced object')
-        self.b(' *')
-        self.b(' * Represents the signature of a callback for the signal %s.'
+        self.d(' * @user_data: User-supplied data')
+        self.d(' * @weak_object: User-supplied weakly referenced object')
+        self.d(' *')
+        self.d(' * Represents the signature of a callback for the signal %s.'
                % member)
-        self.b(' */')
+        self.d(' */')
+        self.d('')
+
         self.h('typedef void (*%s) (%sproxy,'
                % (callback_name, self.proxy_cls))
 
@@ -290,31 +298,33 @@ class Generator(object):
         # emitted the 'invalidated' signal, or because the weakly referenced
         # object has gone away.
 
-        self.b('/**')
-        self.b(' * %s_%s_connect_to_%s:'
+        self.d('/**')
+        self.d(' * %s_%s_connect_to_%s:'
                % (self.prefix_lc, iface_lc, member_lc))
-        self.b(' * @proxy: %s' % self.proxy_doc)
-        self.b(' * @callback: Callback to be called when the signal is')
-        self.b(' *   received')
-        self.b(' * @user_data: User-supplied data for the callback')
-        self.b(' * @destroy: Destructor for the user-supplied data, which')
-        self.b(' *   will be called when this signal is disconnected, or')
-        self.b(' *   before this function returns %NULL')
-        self.b(' * @weak_object: A #GObject which will be weakly referenced; ')
-        self.b(' *   if it is destroyed, this callback will automatically be')
-        self.b(' *   disconnected')
-        self.b(' * @error: If not %NULL, used to raise an error if %NULL is')
-        self.b(' *   returned')
-        self.b(' *')
-        self.b(' * Connect a handler to the signal %s.' % member)
-        self.b(' *')
-        self.b(' * %s' % xml_escape(get_docstring(signal) or '(Undocumented)'))
-        self.b(' *')
-        self.b(' * Returns: a #TpProxySignalConnection containing all of the')
-        self.b(' * above, which can be used to disconnect the signal; or')
-        self.b(' * %NULL if the proxy does not have the desired interface')
-        self.b(' * or has become invalid.')
-        self.b(' */')
+        self.d(' * @proxy: %s' % self.proxy_doc)
+        self.d(' * @callback: Callback to be called when the signal is')
+        self.d(' *   received')
+        self.d(' * @user_data: User-supplied data for the callback')
+        self.d(' * @destroy: Destructor for the user-supplied data, which')
+        self.d(' *   will be called when this signal is disconnected, or')
+        self.d(' *   before this function returns %NULL')
+        self.d(' * @weak_object: A #GObject which will be weakly referenced; ')
+        self.d(' *   if it is destroyed, this callback will automatically be')
+        self.d(' *   disconnected')
+        self.d(' * @error: If not %NULL, used to raise an error if %NULL is')
+        self.d(' *   returned')
+        self.d(' *')
+        self.d(' * Connect a handler to the signal %s.' % member)
+        self.d(' *')
+        self.d(' * %s' % xml_escape(get_docstring(signal) or '(Undocumented)'))
+        self.d(' *')
+        self.d(' * Returns: a #TpProxySignalConnection containing all of the')
+        self.d(' * above, which can be used to disconnect the signal; or')
+        self.d(' * %NULL if the proxy does not have the desired interface')
+        self.d(' * or has become invalid.')
+        self.d(' */')
+        self.d('')
+
         self.h('TpProxySignalConnection *%s_%s_connect_to_%s (%sproxy,'
                % (self.prefix_lc, iface_lc, member_lc, self.proxy_arg))
         self.h('    %s callback,' % callback_name)
@@ -322,6 +332,7 @@ class Generator(object):
         self.h('    GDestroyNotify destroy,')
         self.h('    GObject *weak_object,')
         self.h('    GError **error);')
+        self.h('')
 
         self.b('TpProxySignalConnection *')
         self.b('%s_%s_connect_to_%s (%sproxy,'
@@ -361,8 +372,6 @@ class Generator(object):
         self.b('}')
         self.b('')
 
-        self.h('')
-
     def do_method(self, iface, method):
         iface_lc = iface.lower()
 
@@ -414,34 +423,35 @@ class Generator(object):
         #       gpointer user_data,
         #       GObject *weak_object);
 
-        self.b('/**')
-        self.b(' * %s_%s_callback_for_%s:'
+        self.d('/**')
+        self.d(' * %s_%s_callback_for_%s:'
                % (self.prefix_lc, iface_lc, member_lc))
-        self.b(' * @proxy: the proxy on which the call was made')
+        self.d(' * @proxy: the proxy on which the call was made')
 
         for arg in out_args:
             name, info, tp_type, elt = arg
             ctype, gtype, marshaller, pointer = info
 
-            self.b(' * @%s: Used to return an \'out\' argument if @error is '
+            self.d(' * @%s: Used to return an \'out\' argument if @error is '
                    '%%NULL: %s'
                    % (name, xml_escape(get_docstring(elt) or '(Undocumented)')))
 
-        self.b(' * @error: %NULL on success, or an error on failure')
-        self.b(' * @user_data: user-supplied data')
-        self.b(' * @weak_object: user-supplied object')
-        self.b(' *')
-        self.b(' * Signature of the callback called when a %s method call'
+        self.d(' * @error: %NULL on success, or an error on failure')
+        self.d(' * @user_data: user-supplied data')
+        self.d(' * @weak_object: user-supplied object')
+        self.d(' *')
+        self.d(' * Signature of the callback called when a %s method call'
                % member)
-        self.b(' * succeeds or fails.')
+        self.d(' * succeeds or fails.')
 
         deprecated = method.getElementsByTagName('tp:deprecated')
         if deprecated:
             d = deprecated[0]
-            self.b(' *')
-            self.b(' * Deprecated: %s' % xml_escape(get_deprecated(d)))
+            self.d(' *')
+            self.d(' * Deprecated: %s' % xml_escape(get_deprecated(d)))
 
-        self.b(' */')
+        self.d(' */')
+        self.d('')
 
         callback_name = '%s_%s_callback_for_%s' % (self.prefix_lc, iface_lc,
                                                    member_lc)
@@ -666,49 +676,51 @@ class Generator(object):
                % (self.prefix_lc, iface_lc, member_lc, self.proxy_arg))
         self.h('    gint timeout_ms,')
 
-        self.b('/**')
-        self.b(' * %s_%s_call_%s:'
+        self.d('/**')
+        self.d(' * %s_%s_call_%s:'
                % (self.prefix_lc, iface_lc, member_lc))
-        self.b(' * @proxy: the #TpProxy')
-        self.b(' * @timeout_ms: the timeout in milliseconds, or -1 to use the')
-        self.b(' *   default')
+        self.d(' * @proxy: the #TpProxy')
+        self.d(' * @timeout_ms: the timeout in milliseconds, or -1 to use the')
+        self.d(' *   default')
 
         for arg in in_args:
             name, info, tp_type, elt = arg
             ctype, gtype, marshaller, pointer = info
 
-            self.b(' * @%s: Used to pass an \'in\' argument: %s'
+            self.d(' * @%s: Used to pass an \'in\' argument: %s'
                    % (name, xml_escape(get_docstring(elt) or '(Undocumented)')))
 
-        self.b(' * @callback: called when the method call succeeds or fails;')
-        self.b(' *   may be %NULL to make a "fire and forget" call with no ')
-        self.b(' *   reply tracking')
-        self.b(' * @user_data: user-supplied data passed to the callback;')
-        self.b(' *   must be %NULL if @callback is %NULL')
-        self.b(' * @destroy: called with the user_data as argument, after the')
-        self.b(' *   call has succeeded, failed or been cancelled;')
-        self.b(' *   must be %NULL if @callback is %NULL')
-        self.b(' * @weak_object: If not %NULL, a #GObject which will be ')
-        self.b(' *   weakly referenced; if it is destroyed, this call ')
-        self.b(' *   will automatically be cancelled. Must be %NULL if ')
-        self.b(' *   @callback is %NULL')
-        self.b(' *')
-        self.b(' * Start a %s method call.' % member)
-        self.b(' *')
-        self.b(' * %s' % xml_escape(get_docstring(method) or '(Undocumented)'))
-        self.b(' *')
-        self.b(' * Returns: a #TpProxyPendingCall representing the call in')
-        self.b(' *  progress. It is borrowed from the object, and will become')
-        self.b(' *  invalid when the callback is called, the call is')
-        self.b(' *  cancelled or the #TpProxy becomes invalid.')
+        self.d(' * @callback: called when the method call succeeds or fails;')
+        self.d(' *   may be %NULL to make a "fire and forget" call with no ')
+        self.d(' *   reply tracking')
+        self.d(' * @user_data: user-supplied data passed to the callback;')
+        self.d(' *   must be %NULL if @callback is %NULL')
+        self.d(' * @destroy: called with the user_data as argument, after the')
+        self.d(' *   call has succeeded, failed or been cancelled;')
+        self.d(' *   must be %NULL if @callback is %NULL')
+        self.d(' * @weak_object: If not %NULL, a #GObject which will be ')
+        self.d(' *   weakly referenced; if it is destroyed, this call ')
+        self.d(' *   will automatically be cancelled. Must be %NULL if ')
+        self.d(' *   @callback is %NULL')
+        self.d(' *')
+        self.d(' * Start a %s method call.' % member)
+        self.d(' *')
+        self.d(' * %s' % xml_escape(get_docstring(method) or '(Undocumented)'))
+        self.d(' *')
+        self.d(' * Returns: a #TpProxyPendingCall representing the call in')
+        self.d(' *  progress. It is borrowed from the object, and will become')
+        self.d(' *  invalid when the callback is called, the call is')
+        self.d(' *  cancelled or the #TpProxy becomes invalid.')
 
         deprecated = method.getElementsByTagName('tp:deprecated')
         if deprecated:
             d = deprecated[0]
-            self.b(' *')
-            self.b(' * Deprecated: %s' % xml_escape(get_deprecated(d)))
+            self.d(' *')
+            self.d(' * Deprecated: %s' % xml_escape(get_deprecated(d)))
+
+        self.d(' */')
+        self.d('')
 
-        self.b(' */')
         self.b('TpProxyPendingCall *\n%s_%s_call_%s (%sproxy,'
                % (self.prefix_lc, iface_lc, member_lc, self.proxy_arg))
         self.b('    gint timeout_ms,')
@@ -825,6 +837,7 @@ class Generator(object):
                                      in_args, out_args, collect_callback)
 
         # leave a gap for the end of the method
+        self.d('')
         self.b('')
         self.h('')
 
@@ -921,51 +934,53 @@ class Generator(object):
                % (self.prefix_lc, iface_lc, member_lc, self.proxy_arg))
         self.h('    gint timeout_ms,')
 
-        self.b('/**')
-        self.b(' * %s_%s_run_%s:' % (self.prefix_lc, iface_lc, member_lc))
-        self.b(' * @proxy: %s' % self.proxy_doc)
-        self.b(' * @timeout_ms: Timeout in milliseconds, or -1 for default')
+        self.d('/**')
+        self.d(' * %s_%s_run_%s:' % (self.prefix_lc, iface_lc, member_lc))
+        self.d(' * @proxy: %s' % self.proxy_doc)
+        self.d(' * @timeout_ms: Timeout in milliseconds, or -1 for default')
 
         for arg in in_args:
             name, info, tp_type, elt = arg
             ctype, gtype, marshaller, pointer = info
 
-            self.b(' * @%s: Used to pass an \'in\' argument: %s'
+            self.d(' * @%s: Used to pass an \'in\' argument: %s'
                    % (name, xml_escape(get_docstring(elt) or '(Undocumented)')))
 
         for arg in out_args:
             name, info, tp_type, elt = arg
             ctype, gtype, marshaller, pointer = info
 
-            self.b(' * @%s: Used to return an \'out\' argument if %%TRUE is '
+            self.d(' * @%s: Used to return an \'out\' argument if %%TRUE is '
                    'returned: %s'
                    % (name, xml_escape(get_docstring(elt) or '(Undocumented)')))
 
-        self.b(' * @error: If not %NULL, used to return errors if %FALSE ')
-        self.b(' *  is returned')
-        self.b(' * @loop: If not %NULL, set before re-entering ')
-        self.b(' *  the main loop, to point to a #GMainLoop ')
-        self.b(' *  which can be used to cancel this call with ')
-        self.b(' *  g_main_loop_quit(), causing a return of ')
-        self.b(' *  %FALSE with @error set to %TP_DBUS_ERROR_CANCELLED')
-        self.b(' *')
-        self.b(' * Call the method %s and run the main loop' % member)
-        self.b(' * until it returns. Before calling this method, you must')
-        self.b(' * add a reference to any borrowed objects you need to keep,')
-        self.b(' * and generally ensure that everything is in a consistent')
-        self.b(' * state.')
-        self.b(' *')
-        self.b(' * %s' % xml_escape(get_docstring(method) or '(Undocumented)'))
-        self.b(' *')
-        self.b(' * Returns: TRUE on success, FALSE and sets @error on error')
+        self.d(' * @error: If not %NULL, used to return errors if %FALSE ')
+        self.d(' *  is returned')
+        self.d(' * @loop: If not %NULL, set before re-entering ')
+        self.d(' *  the main loop, to point to a #GMainLoop ')
+        self.d(' *  which can be used to cancel this call with ')
+        self.d(' *  g_main_loop_quit(), causing a return of ')
+        self.d(' *  %FALSE with @error set to %TP_DBUS_ERROR_CANCELLED')
+        self.d(' *')
+        self.d(' * Call the method %s and run the main loop' % member)
+        self.d(' * until it returns. Before calling this method, you must')
+        self.d(' * add a reference to any borrowed objects you need to keep,')
+        self.d(' * and generally ensure that everything is in a consistent')
+        self.d(' * state.')
+        self.d(' *')
+        self.d(' * %s' % xml_escape(get_docstring(method) or '(Undocumented)'))
+        self.d(' *')
+        self.d(' * Returns: TRUE on success, FALSE and sets @error on error')
 
         deprecated = method.getElementsByTagName('tp:deprecated')
         if deprecated:
             d = deprecated[0]
-            self.b(' *')
-            self.b(' * Deprecated: %s' % xml_escape(get_deprecated(d)))
+            self.d(' *')
+            self.d(' * Deprecated: %s' % xml_escape(get_deprecated(d)))
+
+        self.d(' */')
+        self.d('')
 
-        self.b(' */')
         self.b('gboolean\n%s_%s_run_%s (%sproxy,'
                % (self.prefix_lc, iface_lc, member_lc, self.proxy_arg))
         self.b('    gint timeout_ms,')
@@ -1185,6 +1200,7 @@ class Generator(object):
 
         open(self.basename + '.h', 'w').write('\n'.join(self.__header))
         open(self.basename + '-body.h', 'w').write('\n'.join(self.__body))
+        open(self.basename + '-gtk-doc.h', 'w').write('\n'.join(self.__docs))
 
 
 def types_to_gtypes(types):
diff --git a/tools/glib-errors-str-gen.py b/tools/glib-errors-str-gen.py
index 9ea76956e..a948a7ca8 100644
--- a/tools/glib-errors-str-gen.py
+++ b/tools/glib-errors-str-gen.py
@@ -13,13 +13,23 @@ class Generator(object):
 
         self.__header = []
         self.__body = []
+        self.__docs = []
 
     def h(self, s):
+        if isinstance(s, unicode):
+            s = s.encode('utf-8')
         self.__header.append(s)
 
     def b(self, s):
+        if isinstance(s, unicode):
+            s = s.encode('utf-8')
         self.__body.append(s)
 
+    def d(self, s):
+        if isinstance(s, unicode):
+            s = s.encode('utf-8')
+        self.__docs.append(s)
+
     def __call__(self):
         errors = self.errors.getElementsByTagNameNS(NS_TP, 'error')
 
@@ -38,14 +48,15 @@ class Generator(object):
             name = 'TP_ERROR_STR_' + uc_nick
             error_name = '%s.%s' % (ns, nick)
 
-            self.h('')
-            self.h('/**')
-            self.h(' * %s:' % name)
-            self.h(' *')
-            self.h(' * The D-Bus error name %s' % error_name)
-            self.h(' *')
-            self.h(' * %s' % xml_escape(get_docstring(error)))
-            self.h(' */')
+            self.d('/**')
+            self.d(' * %s:' % name)
+            self.d(' *')
+            self.d(' * The D-Bus error name %s' % error_name)
+            self.d(' *')
+            self.d(' * %s' % xml_escape(get_docstring(error)))
+            self.d(' */')
+            self.d('')
+
             self.h('#define %s "%s"' % (name, error_name))
 
             self.b('      case TP_ERROR_%s:' % uc_nick)
@@ -62,6 +73,7 @@ class Generator(object):
 
         open(self.basename + '.h', 'w').write('\n'.join(self.__header))
         open(self.basename + '.c', 'w').write('\n'.join(self.__body))
+        open(self.basename + '-gtk-doc.h', 'w').write('\n'.join(self.__docs))
 
 if __name__ == '__main__':
     argv = sys.argv[1:]
diff --git a/tools/glib-ginterface-gen.py b/tools/glib-ginterface-gen.py
index 3373333f8..04509fd79 100644
--- a/tools/glib-ginterface-gen.py
+++ b/tools/glib-ginterface-gen.py
@@ -41,6 +41,7 @@ class Generator(object):
         self.dom = dom
         self.__header = []
         self.__body = []
+        self.__docs = []
 
         assert prefix.endswith('_')
         assert not signal_marshal_prefix.endswith('_')
@@ -74,11 +75,20 @@ class Generator(object):
         self.allow_havoc = allow_havoc
 
     def h(self, s):
+        if isinstance(s, unicode):
+            s = s.encode('utf-8')
         self.__header.append(s)
 
     def b(self, s):
+        if isinstance(s, unicode):
+            s = s.encode('utf-8')
         self.__body.append(s)
 
+    def d(self, s):
+        if isinstance(s, unicode):
+            s = s.encode('utf-8')
+        self.__docs.append(s)
+
     def do_node(self, node):
         node_name = node.getAttribute('name').replace('/', '')
         node_name_mixed = self.node_name_mixed = node_name.replace('_', '')
@@ -158,51 +168,54 @@ class Generator(object):
         self.b('}')
         self.b('')
 
-        self.h('/**')
-        self.h(' * %s%s:' % (self.Prefix, node_name_mixed))
-        self.h(' *')
-        self.h(' * Dummy typedef representing any implementation of this '
+        self.d('/**')
+        self.d(' * %s%s:' % (self.Prefix, node_name_mixed))
+        self.d(' *')
+        self.d(' * Dummy typedef representing any implementation of this '
                'interface.')
-        self.h(' */')
+        self.d(' */')
+
         self.h('typedef struct _%s%s %s%s;'
                % (self.Prefix, node_name_mixed, self.Prefix, node_name_mixed))
         self.h('')
-        self.h('/**')
-        self.h(' * %s%sClass:' % (self.Prefix, node_name_mixed))
-        self.h(' *')
-        self.h(' * The class of %s%s.' % (self.Prefix, node_name_mixed))
+
+        self.d('/**')
+        self.d(' * %s%sClass:' % (self.Prefix, node_name_mixed))
+        self.d(' *')
+        self.d(' * The class of %s%s.' % (self.Prefix, node_name_mixed))
 
         if methods:
-            self.h(' *')
-            self.h(' * In a full implementation of this interface (i.e. all')
-            self.h(' * methods implemented), the interface initialization')
-            self.h(' * function used in G_IMPLEMENT_INTERFACE() would')
-            self.h(' * typically look like this:')
-            self.h(' *')
-            self.h(' * <programlisting>')
-            self.h(' * static void')
-            self.h(' * implement_%s (gpointer klass,' % self.node_name_lc)
-            self.h(' *     gpointer unused G_GNUC_UNUSED)')
-            self.h(' * {')
-            self.h(' * #define IMPLEMENT(x) %s%s_implement_&num;&num;x (\\'
+            self.d(' *')
+            self.d(' * In a full implementation of this interface (i.e. all')
+            self.d(' * methods implemented), the interface initialization')
+            self.d(' * function used in G_IMPLEMENT_INTERFACE() would')
+            self.d(' * typically look like this:')
+            self.d(' *')
+            self.d(' * <programlisting>')
+            self.d(' * static void')
+            self.d(' * implement_%s (gpointer klass,' % self.node_name_lc)
+            self.d(' *     gpointer unused G_GNUC_UNUSED)')
+            self.d(' * {')
+            self.d(' * #define IMPLEMENT(x) %s%s_implement_&num;&num;x (\\'
                    % (self.prefix_, self.node_name_lc))
-            self.h(' *   klass, my_object_&num;&num;x)')
+            self.d(' *   klass, my_object_&num;&num;x)')
 
             for method in methods:
                 class_member_name = method.getAttribute('tp:name-for-bindings')
                 class_member_name = class_member_name.lower()
-                self.h(' *   IMPLEMENT (%s);' % class_member_name)
+                self.d(' *   IMPLEMENT (%s);' % class_member_name)
 
-            self.h(' * #undef IMPLEMENT')
-            self.h(' * }')
-            self.h(' * </programlisting>')
+            self.d(' * #undef IMPLEMENT')
+            self.d(' * }')
+            self.d(' * </programlisting>')
         else:
-            self.h(' * This interface has no D-Bus methods, so an')
-            self.h(' * implementation can typically pass %NULL to')
-            self.h(' * G_IMPLEMENT_INTERFACE() as the interface')
-            self.h(' * initialization function.')
+            self.d(' * This interface has no D-Bus methods, so an')
+            self.d(' * implementation can typically pass %NULL to')
+            self.d(' * G_IMPLEMENT_INTERFACE() as the interface')
+            self.d(' * initialization function.')
 
-        self.h(' */')
+        self.d(' */')
+        self.d('')
 
         self.h('typedef struct _%s%sClass %s%sClass;'
                % (self.Prefix, node_name_mixed, self.Prefix, node_name_mixed))
@@ -474,18 +487,19 @@ class Generator(object):
             else:
                 out_args.append(struct)
 
-        # Implementation type declaration (in header, docs in body)
-        self.b('/**')
-        self.b(' * %s:' % impl_name)
-        self.b(' * @self: The object implementing this interface')
+        # Implementation type declaration (in header, docs separated)
+        self.d('/**')
+        self.d(' * %s:' % impl_name)
+        self.d(' * @self: The object implementing this interface')
         for (ctype, name) in in_args:
-            self.b(' * @%s: %s (FIXME, generate documentation)'
+            self.d(' * @%s: %s (FIXME, generate documentation)'
                    % (name, ctype))
-        self.b(' * @context: Used to return values or throw an error')
-        self.b(' *')
-        self.b(' * The signature of an implementation of the D-Bus method')
-        self.b(' * %s on interface %s.' % (dbus_method_name, self.iface_name))
-        self.b(' */')
+        self.d(' * @context: Used to return values or throw an error')
+        self.d(' *')
+        self.d(' * The signature of an implementation of the D-Bus method')
+        self.d(' * %s on interface %s.' % (dbus_method_name, self.iface_name))
+        self.d(' */')
+
         self.h('typedef void (*%s) (%s%s *self,'
           % (impl_name, self.Prefix, self.node_name_mixed))
         for (ctype, name) in in_args:
@@ -530,18 +544,19 @@ class Generator(object):
                % (self.prefix_, self.node_name_lc, class_member_name,
                   self.Prefix, self.node_name_mixed, impl_name))
 
-        self.b('/**')
-        self.b(' * %s%s_implement_%s:'
+        self.d('/**')
+        self.d(' * %s%s_implement_%s:'
                % (self.prefix_, self.node_name_lc, class_member_name))
-        self.b(' * @klass: A class whose instances implement this interface')
-        self.b(' * @impl: A callback used to implement the %s D-Bus method'
+        self.d(' * @klass: A class whose instances implement this interface')
+        self.d(' * @impl: A callback used to implement the %s D-Bus method'
                % dbus_method_name)
-        self.b(' *')
-        self.b(' * Register an implementation for the %s method in the vtable'
+        self.d(' *')
+        self.d(' * Register an implementation for the %s method in the vtable'
                % dbus_method_name)
-        self.b(' * of an implementation of this interface. To be called from')
-        self.b(' * the interface init function.')
-        self.b(' */')
+        self.d(' * of an implementation of this interface. To be called from')
+        self.d(' * the interface init function.')
+        self.d(' */')
+
         self.b('void')
         self.b('%s%s_implement_%s (%s%sClass *klass, %s impl)'
                % (self.prefix_, self.node_name_lc, class_member_name,
@@ -552,16 +567,18 @@ class Generator(object):
         self.b('')
 
         # Return convenience function (static inline, in header)
-        self.h('/**')
-        self.h(' * %s:' % ret_name)
-        self.h(' * @context: The D-Bus method invocation context')
+        self.d('/**')
+        self.d(' * %s:' % ret_name)
+        self.d(' * @context: The D-Bus method invocation context')
         for (ctype, name) in out_args:
-            self.h(' * @%s: %s (FIXME, generate documentation)'
+            self.d(' * @%s: %s (FIXME, generate documentation)'
                    % (name, ctype))
-        self.h(' *')
-        self.h(' * Return successfully by calling dbus_g_method_return().')
-        self.h(' * This inline function exists only to provide type-safety.')
-        self.h(' */')
+        self.d(' *')
+        self.d(' * Return successfully by calling dbus_g_method_return().')
+        self.d(' * This inline function exists only to provide type-safety.')
+        self.d(' */')
+        self.d('')
+
         tmp = (['DBusGMethodInvocation *context'] +
                [ctype + name for (ctype, name) in out_args])
         self.h('static inline')
@@ -631,17 +648,17 @@ class Generator(object):
 
         # FIXME: emit docs
 
-        self.b('/**')
-        self.b(' * %s:' % stub_name)
-        self.b(' * @instance: The object implementing this interface')
+        self.d('/**')
+        self.d(' * %s:' % stub_name)
+        self.d(' * @instance: The object implementing this interface')
         for (ctype, name, gtype) in args:
-            self.b(' * @%s: %s (FIXME, generate documentation)'
+            self.d(' * @%s: %s (FIXME, generate documentation)'
                    % (name, ctype))
-        self.b(' *')
-        self.b(' * Type-safe wrapper around g_signal_emit to emit the')
-        self.b(' * %s signal on interface %s.'
+        self.d(' *')
+        self.d(' * Type-safe wrapper around g_signal_emit to emit the')
+        self.d(' * %s signal on interface %s.'
                % (dbus_name, self.iface_name))
-        self.b(' */')
+        self.d(' */')
 
         self.b('void')
         self.b(('%s (' % stub_name) + (',\n    '.join(tmp)) + ')')
@@ -657,16 +674,19 @@ class Generator(object):
 
         signal_name = dbus_gutils_wincaps_to_uscore(dbus_name).replace('_',
                 '-')
-        in_base_init.append('  /**')
-        in_base_init.append('   * %s%s::%s:'
+
+        self.d('/**')
+        self.d(' * %s%s::%s:'
                 % (self.Prefix, self.node_name_mixed, signal_name))
         for (ctype, name, gtype) in args:
-            in_base_init.append('   * @%s: %s (FIXME, generate documentation)'
+            self.d(' * @%s: %s (FIXME, generate documentation)'
                    % (name, ctype))
-        in_base_init.append('   *')
-        in_base_init.append('   * The %s D-Bus signal is emitted whenever '
+        self.d(' *')
+        self.d(' * The %s D-Bus signal is emitted whenever '
                 'this GObject signal is.' % dbus_name)
-        in_base_init.append('   */')
+        self.d(' */')
+        self.d('')
+
         in_base_init.append('  %s_signals[%s] ='
                             % (self.node_name_lc, const_name))
         in_base_init.append('  g_signal_new ("%s",' % signal_name)
@@ -724,6 +744,7 @@ class Generator(object):
         self.b('')
         open(self.basename + '.h', 'w').write('\n'.join(self.__header))
         open(self.basename + '.c', 'w').write('\n'.join(self.__body))
+        open(self.basename + '-gtk-doc.h', 'w').write('\n'.join(self.__docs))
 
 
 def cmdline_error():
diff --git a/tools/glib-gtypes-generator.py b/tools/glib-gtypes-generator.py
index ebc2ad4c9..a49c36e7f 100644
--- a/tools/glib-gtypes-generator.py
+++ b/tools/glib-gtypes-generator.py
@@ -44,8 +44,9 @@ class GTypesGenerator(object):
 
         self.header = open(output + '.h', 'w')
         self.body = open(output + '-body.h', 'w')
+        self.docs = open(output + '-gtk-doc.h', 'w')
 
-        for f in (self.header, self.body):
+        for f in (self.header, self.body, self.docs):
             f.write('/* Auto-generated, do not edit.\n *\n'
                     ' * This file may be distributed under the same terms\n'
                     ' * as the specification from which it was generated.\n'
@@ -70,6 +71,9 @@ class GTypesGenerator(object):
     def c(self, code):
         self.body.write(code.encode("utf-8"))
 
+    def d(self, code):
+        self.docs.write(code.encode('utf-8'))
+
     def do_mapping_header(self, mapping):
         members = mapping.getElementsByTagNameNS(NS_TP, 'member')
         assert len(members) == 2
@@ -85,41 +89,41 @@ class GTypesGenerator(object):
 
         docstring = get_docstring(mapping) or '(Undocumented)'
 
-        self.h('/**\n * %s:\n *\n' % name)
-        self.h(' * %s\n' % xml_escape(docstring))
-        self.h(' *\n')
-        self.h(' * This macro expands to a call to a function\n')
-        self.h(' * that returns the #GType of a #GHashTable\n')
-        self.h(' * appropriate for representing a D-Bus\n')
-        self.h(' * dictionary of signature\n')
-        self.h(' * <literal>a{%s}</literal>.\n' % impl_sig)
-        self.h(' *\n')
+        self.d('/**\n * %s:\n *\n' % name)
+        self.d(' * %s\n' % xml_escape(docstring))
+        self.d(' *\n')
+        self.d(' * This macro expands to a call to a function\n')
+        self.d(' * that returns the #GType of a #GHashTable\n')
+        self.d(' * appropriate for representing a D-Bus\n')
+        self.d(' * dictionary of signature\n')
+        self.d(' * <literal>a{%s}</literal>.\n' % impl_sig)
+        self.d(' *\n')
 
         key, value = members
 
-        self.h(' * Keys (D-Bus type <literal>%s</literal>,\n'
+        self.d(' * Keys (D-Bus type <literal>%s</literal>,\n'
                           % key.getAttribute('type'))
         tp_type = key.getAttributeNS(NS_TP, 'type')
         if tp_type:
-            self.h(' * type <literal>%s</literal>,\n' % tp_type)
-        self.h(' * named <literal>%s</literal>):\n'
+            self.d(' * type <literal>%s</literal>,\n' % tp_type)
+        self.d(' * named <literal>%s</literal>):\n'
                           % key.getAttribute('name'))
         docstring = get_docstring(key) or '(Undocumented)'
-        self.h(' * %s\n' % xml_escape(docstring))
-        self.h(' *\n')
+        self.d(' * %s\n' % xml_escape(docstring))
+        self.d(' *\n')
 
-        self.h(' * Values (D-Bus type <literal>%s</literal>,\n'
+        self.d(' * Values (D-Bus type <literal>%s</literal>,\n'
                           % value.getAttribute('type'))
         tp_type = value.getAttributeNS(NS_TP, 'type')
         if tp_type:
-            self.h(' * type <literal>%s</literal>,\n' % tp_type)
-        self.h(' * named <literal>%s</literal>):\n'
+            self.d(' * type <literal>%s</literal>,\n' % tp_type)
+        self.d(' * named <literal>%s</literal>):\n'
                           % value.getAttribute('name'))
         docstring = get_docstring(value) or '(Undocumented)'
-        self.h(' * %s\n' % xml_escape(docstring))
-        self.h(' *\n')
+        self.d(' * %s\n' % xml_escape(docstring))
+        self.d(' *\n')
 
-        self.h(' */\n')
+        self.d(' */\n')
 
         self.h('#define %s (%s ())\n\n' % (name, impl))
         self.need_mappings[impl_sig] = esc_impl_sig
@@ -130,11 +134,12 @@ class GTypesGenerator(object):
             contents_sig = 'a{' + impl_sig + '}'
             esc_contents_sig = escape_as_identifier(contents_sig)
             impl = self.prefix_ + 'type_dbus_array_of_' + esc_contents_sig
-            self.h('/**\n * %s:\n\n' % gtype_name)
-            self.h(' * Expands to a call to a function\n')
-            self.h(' * that returns the #GType of a #GPtrArray\n')
-            self.h(' * of #%s.\n' % name)
-            self.h(' */\n')
+            self.d('/**\n * %s:\n\n' % gtype_name)
+            self.d(' * Expands to a call to a function\n')
+            self.d(' * that returns the #GType of a #GPtrArray\n')
+            self.d(' * of #%s.\n' % name)
+            self.d(' */\n\n')
+
             self.h('#define %s (%s ())\n\n' % (gtype_name, impl))
             self.need_other_arrays[contents_sig] = esc_contents_sig
 
@@ -157,41 +162,43 @@ class GTypesGenerator(object):
                 docstring = '(Undocumented)'
         else:
             docstring = '(Undocumented)'
-        self.h('/**\n * %s:\n\n' % name)
-        self.h(' * %s\n' % xml_escape(docstring))
-        self.h(' *\n')
-        self.h(' * This macro expands to a call to a function\n')
-        self.h(' * that returns the #GType of a #GValueArray\n')
-        self.h(' * appropriate for representing a D-Bus struct\n')
-        self.h(' * with signature <literal>(%s)</literal>.\n'
+        self.d('/**\n * %s:\n\n' % name)
+        self.d(' * %s\n' % xml_escape(docstring))
+        self.d(' *\n')
+        self.d(' * This macro expands to a call to a function\n')
+        self.d(' * that returns the #GType of a #GValueArray\n')
+        self.d(' * appropriate for representing a D-Bus struct\n')
+        self.d(' * with signature <literal>(%s)</literal>.\n'
                           % impl_sig)
-        self.h(' *\n')
+        self.d(' *\n')
 
         for i, member in enumerate(members):
-            self.h(' * Member %d (D-Bus type '
+            self.d(' * Member %d (D-Bus type '
                               '<literal>%s</literal>,\n'
                               % (i, member.getAttribute('type')))
             tp_type = member.getAttributeNS(NS_TP, 'type')
             if tp_type:
-                self.h(' * type <literal>%s</literal>,\n' % tp_type)
-            self.h(' * named <literal>%s</literal>):\n'
+                self.d(' * type <literal>%s</literal>,\n' % tp_type)
+            self.d(' * named <literal>%s</literal>):\n'
                               % member.getAttribute('name'))
             docstring = get_docstring(member) or '(Undocumented)'
-            self.h(' * %s\n' % xml_escape(docstring))
-            self.h(' *\n')
+            self.d(' * %s\n' % xml_escape(docstring))
+            self.d(' *\n')
+
+        self.d(' */\n\n')
 
-        self.h(' */\n')
         self.h('#define %s (%s ())\n\n' % (name, impl))
 
         array_name = struct.getAttribute('array-name')
         if array_name != '':
             array_name = (self.PREFIX_ + 'ARRAY_TYPE_' + array_name.upper())
             impl = self.prefix_ + 'type_dbus_array_' + esc_impl_sig
-            self.h('/**\n * %s:\n\n' % array_name)
-            self.h(' * Expands to a call to a function\n')
-            self.h(' * that returns the #GType of a #GPtrArray\n')
-            self.h(' * of #%s.\n' % name)
-            self.h(' */\n')
+            self.d('/**\n * %s:\n\n' % array_name)
+            self.d(' * Expands to a call to a function\n')
+            self.d(' * that returns the #GType of a #GPtrArray\n')
+            self.d(' * of #%s.\n' % name)
+            self.d(' */\n\n')
+
             self.h('#define %s (%s ())\n\n' % (array_name, impl))
             self.need_struct_arrays[impl_sig] = esc_impl_sig
 
diff --git a/tools/glib-interfaces-gen.py b/tools/glib-interfaces-gen.py
index ac1f933d0..69c721be3 100644
--- a/tools/glib-interfaces-gen.py
+++ b/tools/glib-interfaces-gen.py
@@ -9,8 +9,13 @@ from libglibcodegen import NS_TP, get_docstring, \
 class Generator(object):
     def __init__(self, prefix, implfile, declfile, dom):
         self.prefix = prefix + '_'
+
+        assert declfile.endswith('.h')
+        docfile = declfile[:-2] + '-gtk-doc.h'
+
         self.impls = open(implfile, 'w')
         self.decls = open(declfile, 'w')
+        self.docs = open(docfile, 'w')
         self.spec = get_by_path(dom, "spec")[0]
 
     def h(self, code):
@@ -19,6 +24,9 @@ class Generator(object):
     def c(self, code):
         self.impls.write(code.encode('utf-8'))
 
+    def d(self, code):
+        self.docs.write(code.encode('utf-8'))
+
     def __call__(self):
         for f in self.h, self.c:
             self.do_header(f)
@@ -50,25 +58,37 @@ class Generator(object):
 
     def do_iface(self, iface):
         parent_name = get_by_path(iface, '../@name')
-        self.h("""\
+        self.d("""\
 /**
  * %(IFACE_DEFINE)s:
  *
  * The interface name "%(name)s"
  */
+""" % {'IFACE_DEFINE' : (self.prefix + 'IFACE_' + \
+            parent_name).upper().replace('/', ''),
+       'name' : iface.getAttribute('name')})
+
+        self.h("""
 #define %(IFACE_DEFINE)s \\
 "%(name)s"
 """ % {'IFACE_DEFINE' : (self.prefix + 'IFACE_' + \
             parent_name).upper().replace('/', ''),
        'name' : iface.getAttribute('name')})
 
-        self.h("""
+        self.d("""
 /**
  * %(IFACE_QUARK_DEFINE)s:
  *
  * Expands to a call to a function that returns a quark for the interface \
 name "%(name)s"
  */
+""" % {'IFACE_QUARK_DEFINE' : (self.prefix + 'IFACE_QUARK_' + \
+            parent_name).upper().replace('/', ''),
+       'iface_quark_func' : (self.prefix + 'iface_quark_' + \
+            parent_name).lower().replace('/', ''),
+       'name' : iface.getAttribute('name')})
+
+        self.h("""
 #define %(IFACE_QUARK_DEFINE)s \\
   (%(iface_quark_func)s ())
 
@@ -99,12 +119,20 @@ GQuark
        'name' : iface.getAttribute('name')})
 
         for prop in iface.getElementsByTagNameNS(None, 'property'):
-            self.decls.write("""
+            self.d("""
 /**
  * %(IFACE_PREFIX)s_%(PROP_UC)s:
  *
  * The fully-qualified property name "%(name)s.%(prop)s"
  */
+""" % {'IFACE_PREFIX' : (self.prefix + 'PROP_' + \
+                parent_name).upper().replace('/', ''),
+           'PROP_UC': prop.getAttributeNS(NS_TP, "name-for-bindings").upper(),
+           'name' : iface.getAttribute('name'),
+           'prop' : prop.getAttribute('name'),
+           })
+
+            self.h("""
 #define %(IFACE_PREFIX)s_%(PROP_UC)s \\
 "%(name)s.%(prop)s"
 """ % {'IFACE_PREFIX' : (self.prefix + 'PROP_' + \
@@ -116,12 +144,20 @@ GQuark
 
 
         for prop in iface.getElementsByTagNameNS(NS_TP, 'contact-attribute'):
-            self.decls.write("""
+            self.d("""
 /**
  * %(TOKEN_PREFIX)s_%(TOKEN_UC)s:
  *
  * The fully-qualified contact attribute token name "%(name)s/%(prop)s"
  */
+""" % {'TOKEN_PREFIX' : (self.prefix + 'TOKEN_' + \
+                parent_name).upper().replace('/', ''),
+           'TOKEN_UC': prop.getAttributeNS(None, "name").upper().replace("-", "_").replace(".", "_"),
+           'name' : iface.getAttribute('name'),
+           'prop' : prop.getAttribute('name'),
+           })
+
+            self.h("""
 #define %(TOKEN_PREFIX)s_%(TOKEN_UC)s \\
 "%(name)s/%(prop)s"
 """ % {'TOKEN_PREFIX' : (self.prefix + 'TOKEN_' + \
@@ -131,16 +167,22 @@ GQuark
            'prop' : prop.getAttribute('name'),
            })
 
-
-
         for prop in iface.getElementsByTagNameNS(NS_TP, 'hct'):
             if (prop.getAttribute('is-family') != "yes"):
-                self.decls.write("""
+                self.d("""
 /**
  * %(TOKEN_PREFIX)s_%(TOKEN_UC)s:
  *
  * The fully-qualified capability token name "%(name)s/%(prop)s"
  */
+""" % {'TOKEN_PREFIX' : (self.prefix + 'TOKEN_' + \
+                parent_name).upper().replace('/', ''),
+           'TOKEN_UC': prop.getAttributeNS(None, "name").upper().replace("-", "_").replace(".", "_"),
+           'name' : iface.getAttribute('name'),
+           'prop' : prop.getAttribute('name'),
+           })
+
+                self.h("""
 #define %(TOKEN_PREFIX)s_%(TOKEN_UC)s \\
 "%(name)s/%(prop)s"
 """ % {'TOKEN_PREFIX' : (self.prefix + 'TOKEN_' + \
@@ -150,8 +192,6 @@ GQuark
            'prop' : prop.getAttribute('name'),
            })
 
-        self.decls.write("\n")
-
 if __name__ == '__main__':
     argv = argv[1:]
     Generator(argv[0], argv[1], argv[2], xml.dom.minidom.parse(argv[3]))()