Descriptive element in introspection()?

[Matthew Johnson]

On Sun Aug 10 20:41, Anders Feder wrote:
> I wouldn't know if this is sufficient for your application, but the
> D-Bus specification defines generic metadata "annotations" which could
> theoretically hold a human-readable description:
> 
> http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format

Yes, and I suggested using these to allow human-readable API
documentation (a-la javadoc) to be produced automatically from the
introspection. In fact, I even wrote a proof-of-concept XSLT stylesheet
for doing so [0,1]. However, there were worries about the size of the
introspection data that would result and objections to using annotations
for this.

Some suggestions were made about using a second method call (IntroDoc)
or an (optional) boolean parameter to Introspection to switch it on, but
no concrete suggestions were made.

I'm keen for this to work though. I think being able to automatically
generate API documentation would be a big win. 

I also think we should include a 'throws' clause in this detailing
exceptions which could be expected (other than the obvious
disconnected/noreply etc).

Matt

0. http://mjj29.matthew.ath.cx/dbus-doc/
1. http://mjj29.matthew.ath.cx/dbus-doc/dbus-test.html

-- 
www.matthew.ath.cx
D-Bus Java
-------------- 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/20080811/68c2539a/attachment.pgp