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

[Kevin Krammer]

On Thursday 22 June 2006 17:50, Frans Englich wrote:
> 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.

It would be nice to have at least optionally.

I see the annotations in the introspection just as a different level of 
documentation.

The signature is enough for DBus, it does not require more information other 
than e.g. (ii)

The annotation is the docs for the bindings, which can improve their 
representation if the know if (ii) is a point or a size.

IMHO it would be nice to have an additional level of information, like that a 
point is a window position, which implies some characteristics like X from 
left to right and Y from top to bottom.

A user level browser could easily take that hints to lookup relevant details.

Developer documentation can be a lot less verbose than what an end user might 
want to use and there is demand for user level automatisation.

Lets assume a desktop application exporting which provides some kind if DBus 
interface has it documented in its manual if there is a chance that it might 
get used by users. Thus some kind of reference to the respective chapter 
would be all that is needed, the documentation browser could look up the 
correct text.

Cheers,
Kevin

-- 
Kevin Krammer <kevin.krammer at gmx.at>
Qt/KDE Developer, Debian User
Moderator: www.mrunix.de (German), www.qtcentre.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/dbus/attachments/20060629/900caf98/attachment.pgp