How to supply the docs [was Re: Introspection and documenting methods - can I help?]

[Frans Englich]

On Thursday 22 June 2006 08:33, 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.

Thanks for bringing this up, I was just about to. I haven't been much into 
DBus, but here's my comments nevertheless.

> 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?

I think it is important to consider how this documentation will be used. As I 
see it, it will only be used by /developers/ in those few cases they need the 
documentation. So, I think the documentation will be used by a statistically 
vanishing amount, in the direction of "0.0001%" users.

Having documentation in a browser that "dynamically" pulls it out is very 
cool, but perhaps that's not motivation. And perhaps it can be achieved in 
other ways.

Supplying documentation on the DBus wire means performance impacts(such as in 
binary size for applictions) meaning it wouldn't surprise me if many skipped 
it, and hence one can't rely on availability.

Keeping two "versions", such as a brief one for online data, and the full docs 
somewhere else, would increase complexity too much for too little gain, I 
think.

Perhaps one could let the doc introspection return URIs to XML files instead? 
Hence the documentation could be on a web site, installed locally, and so on.


Cheers,

		Frans