Re: [PATCH] NM DBUS api documentation build system

[Dan Williams <dcbw redhat com>]

On Tue, 2008-02-05 at 15:46 +0100, Will Stephenson wrote:
> Here's a patch that adds api documentation generation to the NM build system.  
> The code is taken from the Telepathy project.

I think as others have expressed, I think that process adds an extra,
unnecessary step.  I think I'd rather see the following:

1) annotate the introspection/*.xml files using the many-times-proposed
"org.freedesktop.DBus.Doc" annotation name which was designed just for
this.  You'd end up with stuff looking like this:

<interface name="org.freedesktop.NetworkManager.Device">
  <method name="Deactivate">
    <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_device_deactivate"/>
    <annotation name="org.freedesktop.DBus.Doc">
      Deactivates the device, removing applicable routes, IP addresses, and marking the device down.
    </annotation>
  </method>

  <property name="Udi" type="s" access="read">
    <annotation name="org.freedesktop.DBus.Doc">
      The HAL Unique Device Identifier for this device.
    </annotation>
  </property>
...
</interface>

2) Assuming dbus-glib's binding tool ignores annotations it doesn't
recognize (and if it doesn't, we fix it to do so), the binding tool will
just continue as normal creating the glue and bindings file.

3) The optional document generation step (enabled at configure-time with
--enable-docs or something) can run xslt or something on the
introspection XML and generate the HTML documentation.

There are some bits of the code that could stand extra documentation
that aren't part of the D-Bus API directly, like the NMSettings
subclasses.  They are of course D-Bus dictionaries, and the key/value
pairs and types are firmly defined.  While that spec doesn't live in
SVN, it really should live there, and it really should be pulled into
the autogenerated docs for consistency.

Thoughts?

Dan