[RFC] Standard documentation strings

[Tom Cocagne]

Sounds like a great idea Sanel. The lack of a good standard in this
arena is probably a major factor in the generally poor state of D-Bus
API documentation. If you can get a consensus on an API, I'll
definitely add it to txdbus.

Tom

On Wed, Aug 29, 2012 at 6:25 PM, Sanel Zukan <sanelz at gmail.com> wrote:
> Hi all,
>
> I my recent development of DBus Explorer tool [1], I found one feature
> quite handy: documentation strings as part of introspection data.
> DBus Explorer, if found them, will use them alongside method or
> signal prototype and display it in tooltip.
>
> However, this feature differs between implementations and bindings:
> GDBus would use org.gtk.GDBus.DocString annotation and EggDBus (is it
> still used?) has similar approach. However, I noticed some Qt
> introspection xml files would use <tp:docstring> tag, and I'm not sure
> is it stripped by binding tool when the source code is created.
>
> Following the path of GDBus (as I subjectively find it leaner), I'm
> planning to add similar annotation in edelib (the main EDE [2] library
> which has own DBus binding). However, before doing so, is anyone
> interested we (try to) make this annotation standard?
>
> For example, it could be named 'org.freedesktop.DBus.DocString' and
> used with the similar rules used by GDBus; or they can differ.
>
> This feature can be also explored by languages already have builtin
> docstring support, like Python or LISP, when creating service code
> that will dynamically generate introspection replies.
>
> What do you think about it?
>
> Thanks.
> Sanel
>
> [1] http://sanelz.blogspot.com/2012/08/exploring-desktop-objects-2.html
> [2] http://edeproject.org
> _______________________________________________
> dbus mailing list
> dbus at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dbus