Exposing some type details in the introspection XML?

[Simon McVittie]

On Fri, 15 May 2020 at 15:43:19 +0200, Lennart Poettering wrote:
> On Fr, 15.05.20 14:01, Simon McVittie (smcv at collabora.com) wrote:
> > 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.
> 
> Hmm, in sd-bus we generally go the other way: we generate XML from our
> C structures rather than generate C structures from XML.

This has the down side that if you want your XML to contain rich
type/documentation information, it has to be in your C structures.
For information about types, perhaps that's what you want. For
detailed API documentation, probably not?

The GLib toolchain actually does this:

    XML (as a pseudo-IDL)     ---->     C structures   ---->     XML
                          gdbus-codegen           GDBus at runtime

where the XML on the left is human-authored and has doc-comments,
and the XML on the right is the plain introspection XML from the D-Bus
Specification (no proprietary extensions, except perhaps annotations).

> That all said, maybe if there's somebody who wants to work on this:
> maybe XML is a shitty choice for introspectionin 2020.

It's certainly not the easiest language to write in. When I used to work
on Telepathy, I often found myself writing design proposals in an informal
pseudo-IDL:

    interface o.fd.Telepathy.Pokable:
      method Poke(b: with_stick, a{sv}: properties) -> as: ouch
        Poke the object, possibly with a stick. Return the noises it makes.

        with_stick: If true, maintain social distancing.
        properties: Every time we don't add an a{sv} we regret it later.

and wishing I could generate the code from a more formal version of that,
rather than from something as verbose and human-author-unfriendly as XML.

The IDL in
https://blogs.gnome.org/alexl/2020/01/14/introducing-gvariant-schemas/ is
relevant to this topic, although that only describes data types, not entire
D-Bus interfaces.

> And I mean:
> a(sa(sa(sa(sgya{sv})a{sv})a(sa(sga{sv})a{sv})a(sgya{sv})a{sv})a{sv}) ←
> that's just so delicious! Just think about how much more awesome this
> signature string could be if there were structures.

Somewhere, something went horribly wrong...

I'm particularly enjoying the combination of a{sv} for arbitrary
extensibility, and y because i or u would be a larger bitfield than
is required. Both seem correct, but they're a weird juxtaposition.

    smcv