Re: [PATCH] NM DBUS api documentation build system

[Marcel Holtmann <marcel holtmann org>]

Hi Dan,

> > 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>

I really like this. It keeps it actually readable. Has anybody proposed
this as an extension to the D-Bus specification?

Regards

Marcel