How to supply the docs [was Re: Introspection and documenting
methods - can I help?]
englich at kde.org
Thu Jun 22 08:50:51 PDT 2006
On Thursday 22 June 2006 08:33, Philip Rodrigues wrote:
> 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
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
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.
More information about the dbus