Annotation in introspection XML <arg> elements?

[David Zeuthen]

Hey,

On Mon, Nov 10, 2014 at 1:08 PM, Lennart Poettering <mzqohf at 0pointer.de>
wrote:

> The current specification says:
>
>         Method, interface, property, and signal elements may have
>         "annotations", which are generic key/value pairs of metadata.
>
> It doesn't list <arg> elements in that paragraph...
>
> The DTD we ship also doesn't allow annotations within <arg>.
>

For the record, the gdbus-codegen(1) program supports annotations on <arg>
elements - for example to specify that the code generator should use a
GVariant instance for the generator code instead of the "natural" C
type (org.gtk.GDBus.C.ForceGVariant). . I think this usage is meaningful
given that there's no 1:1 correspondence between the D-Bus type system and
whatever language + library-stack you are using. IOW, it's not unlikely you
need to give the code-generator extra hints on a per-argument basis.


>
> Now, I am not sure I want to know qhat the qtdbus annotations are
> supposed to do (it looks very questionnable as it appears to encode
> the parameter index to base 0 in the annotation which seems pretty
> redundant), but I am pretty sure they are not in accordance with the
> D-Bus spec right now.
>
> Two options:
>
> a) file a bug against colord/qt to remove the annotations and generate
>    valid XML data according to the spec and DTD.
>
> b) amend the dbus spec/DTD to allow what colord/qt are doing there.
>

I think it makes sense to update the spec (and DTD) to allow annotations on
<arg> elements.

That said, I think colord is probably broken in two respects

1. At runtime, colord should not return annotations that most are useless
at runtime (as the Qt one seems to be). That's also why gdbus-codegen(1)
will never include any of the org.gtk.GDBus.* annotations (because these
are never used at runtime) in the data it generates for GDBus to generate
the introspection response at runtime.

2. Unless colord is using Qt itself (which I don't think it is but I didn't
check), it should not carry annotations for use in other D-Bus frameworks.
Why? Because if taken to the limit it means that this XML file will end up
carrying annotations for all known code-generators. Instead, code
generators should support "injecting" annotations so they can still use
"upstream" XML interface definition files without requiring that upstream
carry all that baggage. So I think the colord maintainer should just delete
those annotations. As a reference point, gdbus-codegen(1) supports that,
see the --annotate command-line option.

     David
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/dbus/attachments/20141110/d9d8ff1c/attachment.html>