Re: [PATCH] NM DBUS api documentation build system

[Will Stephenson <wstephenson kde org>]

On Tuesday 05 February 2008 17:28:13 Tambet Ingo wrote:
> 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.

As I said, I'm offering to write that documentation as I grok 0.7.  I have to 
do that anyway, I did it once for 0.6.5 when working on knetworkmanager, but 
did it in a way so pragmatically scrappy and good enough only for my own 
needs that I never published it.  Now I've got to repeat the exercise from 
scratch.  

As a responsible open source developer I would not presume to bomb you with 
new stuff without intending to maintain it.

To try and alleviate your concerns about opaque magic, this is how the magic 
works:

1) The patch moves the introspection xml from introspection/ to spec/  
2) I add namespaced documentation to the spec/ xml in the tp namespace eg 
<tp:docstring>blah</tp:docstring>
3) The xslt copies the xml back to introspection/, stripping out the tp 
namespaced items in the process
4) Another xslt generates nice human readable html from spec/ documenting all 
the interfaces, objects, methods, errors and properties.

So the documentation remains valid introspection xml, just plus a bit, and the 
xslt that purifies it again is really simple ("pass everything through that 
isn't tp: prefixed")  The html-ising xslt in 4) is more verbose but not much 
more complex and does not affect the existing build system.

The benefit to having the docu in the xml rather than in a text file is that 
it makes it very easy for developers to document as they change the interface 
so you don't end up with antique text file documentation.  You might even get 
more developers as a result.

Will

-- 
Will Stephenson
IRC: Bille