Re: Where to find useful devel docs?

[Dan Williams <dcbw redhat com>]

On Wed, 2006-03-15 at 10:44 -0500, Derek Atkins wrote:
> Dan Williams <dcbw redhat com> writes:
> 
> > Extensive documentation hasn't historically been an NM strong point,
> > unfortunately.  It's not helped by the fact that you can't use doxygen
> > or whatever for autogeneration of DBUS API docs.
> 
> Hmm that's interesting... Why not?

DBus method descriptions aren't exactly statically analyzable, so any
documentation you could do would convolute the code even more.  You
could likely "fake" the code-comments, but then they wouldn't have any
relation to the actual code that they should refer to.  To process a
dbus method call you essentially have a bit "if (!strcmp()) else if (!
strcmp()) else if..." block that matches the method call name against
ones you support, then dispatches it to the appropriate C function.  But
of course, you can pass anything you like to the C function that
processes the dbus message, since it has nothing to do with the message
arguments that you actually pull of the message itself...

It's not unsolvable, since you can generate docs from DBus Introspection
if you support it.  But that also means you can't have flexible DBUS
calls that take different arguments depending on the arguments that came
earlier, like we do with the NM authentication information stuff.
Admittedly, that's just one function of the NM public API that won't
work here.

Dan