Exposing some type details in the introspection XML?

[Simon McVittie]

On Fri, 15 May 2020 at 02:08:57 +0200, Marc-André Lureau wrote:
> Has there been some attempt at exposing higher-level types, or type
> description, other than just type signatures in the introspection XML?

There have been several, but there is no standard for it.
https://gitlab.freedesktop.org/dbus/dbus/-/issues/120 is the feature
request. https://gitlab.freedesktop.org/dbus/dbus/-/issues/141 is also
related.

I think the best approach is probably to define a more detailed
documentation format (either XML or something more human-readable and
human-writable), and have a tool that can process it to generate
(a) HTML documentation, and (b) the current introspection language.

The Telepathy introspection extensions
https://telepathy.freedesktop.org/wiki/DbusSpec/ (also used by MPRIS2)
are a reasonably comprehensive version, using namespaced XML elements.

GLib's gdbus-codegen understands specially-formatted comments, inspired
by gtk-doc, Doxygen and Javadoc, instead of using markup.

https://gitlab.freedesktop.org/dbus/dbus-doc was an earlier attempt that
never really got anywhere.

You might think that the standard D-Bus introspection annotations are
suitable for this - but unfortunately they aren't suitable for anything
more elaborate than what QtDBus and GDBus already do, because despite
being problematically verbose, their values are constrained to be XML
attribute values, which can't contain markup or significant whitespace
(both of which are likely to be needed for non-trivial documentation).

https://gitlab.freedesktop.org/dbus/dbus/-/issues/158 is a more ambitious
version, redefining the introspection interface by replacing the XML
blobs with D-Bus structured types.

(As you can see from the age of those issues, this has not been anyone's
top priority for a long time.)

    smcv