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.
> 
> The system
> * extends the DBUS introspection xml format with namespaced documentation 
> members
> * replaces introspection xml with this documented xml in spec/
> * regenerates the introspection xml at build time, stripping away the api docu 
> with XSLT
> * generates HTML documentation from the spec/*.xml
> * introduces a build time dependency on xsltproc, and if I adapt the tests, on 
> python.
> * is moving towards being generalised - the AT-SPI project have adopted it too 
> and are producing a RelaxNG schema for the dbus xml extensions.
> * doesn't support builddir != srcdir yet.
> 
> 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.

I certainly want automatically generated API docs; it's a big win for a
lot of reasons.  The D-Bus interface for 0.6.x is actually pretty bad
and not transparently specified.  We've fixed that with 0.7 and we also
do need the API docs to go with it.  I like having browsable docs as
output as well.

What I don't know anything about is the pros and cons of the various
systems of generating that documentation, so I'm not sure I have much
input here.  Tambet did the initial glib introspection stuff so he's
more familiar with the process.

We definitely need the docs, the only question is how exactly to go
about getting them.

Dan