Re: [PATCH] NM DBUS api documentation build system

[Marcel Holtmann <marcel holtmann org>]

Hi Tambet,

> > I haven't actually added any api documentation yet.  I'm working on supporting
> > NM 0.7 in KDE 4 and would do so as I grok 0.7.  The patch just replicates the
> > status quo with the ability to add api docs.  The system can also add a make
> > check target to assure the docu generation is working but I haven't
> > adapted/copied that yet.
> >
> > Another question is, are you interested in async glib binding support?  The
> > system can apparently generate separate async introspection xml but I haven't
> > adapted that either yet as I'm not familiar with the glib bindings.
> >
> > I've tested this locally.  Dan, Tambet: what do you think about integrating
> > it?  It would make NM client developement much easier.
> 
> While I'd like to have always up to date documentation, I'm not sure I
> like this. The patch you sent only removes the introspection XML we
> currently have and adds some XSLT which I can't read (and thus
> maintain). It'll make development easier only if someone actually
> writes that documentation, just converting to more magic makes things
> harder to understand. And again, I like having documentation as much
> as anyone,  but since we have two developers in total (who are busy
> with maintenance work for a lot of time), I personally would rather
> write code. So if anyone wants to help with documentation, it could
> live in a text file for now. When it has enough information, and if
> Dan feels comfortable maintaining XSLT, I wouldn't have anything
> against the proposed solution.

I must agree here. Something that generate the introspection is not
helpful at all. It is hard enough to keep external introspection XML
files in sync with the actual runtime introspection. Why should we have
another thing to maintain. If you could generate the introspection files
from within the source code, that is a different story. Something in
combination with Doxygen.

Regards

Marcel