Documenting dbus IDL (xml) files.

[Gary Cramblitt]

On Tuesday 06 June 2006 04:16, Adriaan de Groot wrote:
> On Tuesday 06 June 2006 09:09, Thiago Macieira wrote:
> > Gary Cramblitt wrote:
> > >Is there some way that dbusidl2cpp could be enhanced to allow
> > > documentation in the IDL xml file without encoding it into the
> > > Q_CLASSINFO definition?
> >
> > I could erase the comment nodes from the XML DOM tree.

Given that there currently is no means for properly handling documentation in 
the .xml files, making this change is premature.  My response is "Leave it as 
is for now."

> >
> > But if you want to document the D-BUS interfaces, you should participate
> > in the on-going discussions on how to do that in a platform-independant
> > way, for all bindings.
> >
> > One thing I can tell you is it won't be Doxygen.

After looking over the dbus mailing list discussions, it seems to come down to 
the following:

1.  There is a requirement to document api's so that they can be introspected 
at runtime using tools like kdbus.  There are concerns about memory usage and 
impact on caching.  For these reasons, the information should be kept very 
brief.

2.  There is also a requirement to provide fuller api documentation for 
programmers to look at.  There is (so far) no agreement how to do this in a 
platform independent way that would be compatible with existing automated 
documentation tools such as Doxygen, JavaDoc, etc.

3.  None of these issues have been resolved.  The 1.0 implementation of dbus 
provides no means of providing documentation other than the awkward  
annotation tags.  The plan is to address this in later versions.

>
> For this reason I'd suggest sticking the documentation into a .h file with
> some kind of fake class / namespace / file settings and using @fn to name
> the individual functions. It's broken and inconvenient, but the only way to
> get stuff into the visible API documentation at this time.

Adriaan, given that this is the only reasonable way to do it (at this time), 
it would be helpful if you could experiment and provide more detailed 
guidance (on the ebn?).  Some of the things I wondered about for KSpeech:

1.  Should I just leave my existing kspeech.h file in the repository and 
change all the documentation talking about dcop to dbus?  This would leave 
all the existing enum, class, and method declarations in place so that 
Doxygen won't lose its mind.

2.  Or maybe I should rename kspeech.h to kspeechdoc.h and remove all the 
code, leaving nothing but comments?  How exactly do I do that?  Do I leave 
the class declaration in place?  Please explain the @fn marking in more 
detail.  A full example would be great.

3.  There are some enums in the existing kspeech.h and apparently no way to 
define them in the .xml file.  So keeping them in the kspeech.h file would be 
desirable so that code can include them.  Given this, I'm leaning towards the 
#1 approach.

4.  I thought about adding an xml comment to org.kde.kttsd.KSpeech.xml  
saying "See kspeech.h for documentation." so that introspectors would know 
where to find the api documentation, or at least know that it exists.  
Possibly the xml could say "Type 'kde:KSpeech' in Konqueror for api 
documentation."

I fear that we are about to lose a lot of valuable programmer information as 
everyone converts their dcop api code to xml.  Something should be done about 
this and soon.  ATM, I don't have a lot of time to experiment.

>
> In the long run, something to extract the documentation from whatever is
> chosen on the DBUS side in order to feed it into Doxygen would be useful,
> so that the documentation can be written in the XML and still integrate
> with the rest of the KDE documentation.

agreed

-- 
Gary Cramblitt (aka PhantomsDad)
KDE Text-to-Speech Maintainer
http://accessibility.kde.org/developer/kttsd/index.php