Introspection and documenting methods - can I help?

[Daniel P. Berrange]

On Thu, Jun 22, 2006 at 09:33:17AM +0100, Philip Rodrigues wrote:
> Hi,
> I'd really like to see documentation for applications' DBUS methods in KDE 4, 
> since I think this was a notable missing feature in DCOP. So, to that end, 
> I'd like to do what I can to help it along. From reading archives of this 
> list, it seems that this will require:
> 
> 1. Deciding exactly how to serve up the documentation without passing too much 
> data over the wire (eg, modifying Introspect() or introducing Introdoc()). 
> Has this been decided?
> 2. Implementing 1.

My personal preference is to have the documentation "out-of-band" from the
normal introspection data - separate functional data, from that which is
merely informative. So adding some form of Introdoc() method would be my
choice since it avoids breaking backwards compatability, and will avoid
issue of adding many 10-100's of KB to data returned by existing Introspect() 
method.

> 3. Producing the relevant documentation from the Javadoc/PyDoc/Doxygen source.

There is one other point to be decided before this - namely what format
should the documentation returned by Introdoc()  be?  HTML, DocBook XML
fragment per method /property/signal, a complete DocBook XML document
per interface, plain text, an XML format tailored to DBus, something else?

The critical requirement would be that it must be easy to automatically convert
from JavaDoc, POD, PyDoc, etc into the format required by DBus, because the
primary method of documentating classes will always be the language's specific
format.

> Firstly, have I understood the issues correctly? If so, what would be the best 
> way for me to get involved? I'm not really a coder, although I could try if 
> necessary. I do have some experience with XML, so perhaps I could work on 
> step 3.

A proposal for the API, and the documentation format would be a good 
place to start. From there a proof of concept implementation for one
of the higher level language specific bindings would be a useful sanity 
check.

Regards,
Dan.
-- 
|=-            GPG key: http://www.berrange.com/~dan/gpgkey.txt       -=|
|=-       Perl modules: http://search.cpan.org/~danberr/              -=|
|=-           Projects: http://freshmeat.net/~danielpb/               -=|
|=-   berrange at redhat.com  -  Daniel Berrange  -  dan at berrange.com    -=|
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/dbus/attachments/20060622/b54d03c0/attachment.pgp