[PATCH wayland 0/3] "enum" and "bitfield" attributes for protocol XML files

[Auke Booij]

On 5 October 2015 at 14:56, Pekka Paalanen <ppaalanen at gmail.com> wrote:
> On Fri, 26 Jun 2015 16:02:44 +0200
> Auke Booij <auke at tulcod.com> wrote:
>
>> As per last April/May's "enum" attribute discussion, these patches
>> introduce two new attributes to the protocol XML files.
>> The "enum" attribute is given to <arg>uments of type (u)int, and
>> indicates which <enum> should be used for that argument.
>> The "bitfield" attribute can be given to <enum>s, and, if set to "true",
>> indicates that the enum is to be thought of as a bitmask-style value.
>>
>> Although arguments can only refer to enums in specific cases (see the
>> scanner.c changes), this new protocol data should not break the C bindings.
>> It is thinkable that other bindings *do* use the data in a way that breaks
>> the protocol; however such usage will be considered nonstandard.
>>
>> Auke Booij (3):
>>   protocol: introduce the enum argument type
>>   scanner: enforce correct argument type for enums
>>   doc: document new enum attributes and use such data in generated docs
>
> Hi Auke,
>
> so we've had a huge amount of discussion recently and I'm sure you have
> lots of ideas already. I'm not going to summarize that discussion, but
> propose more technical improvements here.
>
> I think it would make sense to order the patch series in reverse:
> 1. XML language spec (and the DTD if you want to update that)
> 2. wayland.xml
> 3. scanner
> 4. doc generator
>
> That way we start with the XML language specification. Then add the new
> things to wayland.xml. At this point we see that old wayland-scanner
> still works. Then update wayland-scanner, and finally the doc
> generator. So the doc patch would be split in two.
>
> Reviewers will then verify the (absence of) changes in the generated C
> bindings.
>
> I think I discussed with Victor in IRC about testing old
> wayland-scanners. It shouldn't be too difficult to write a script that
> checks out each of the ten 1.x.0 Wayland releases, builds
> wayland-scanner from it, and runs it on the tip wayland.xml. Maybe
> someone could contribute such a script. I think it might be handy in
> the future too.
>
> In Patch 1 for the XML language spec, I think you could start a new
> section "XML Language" or such, and specify all these new concepts and
> attributes there. You can start it with a blanket paragraph that says
> the authoritative basic definition of the language is what
> wayland-scanner implements, and this section just adds to that. This
> way we will have a place to start gathering the language doc.
>
> I think the section "code generation" is more like how to do language
> bindings, so if someone wants to get started on that, that would be the
> place. What is right now in "code generation" could be split between
> "basic principles" (we have this XML files thing) and C bindings.
>
> If you want to avoid revising all the patches, you could start by
> posting an RFC of only the first patch. That's what everyone has been
> fighting over anyway. When people are generally happy with that, you
> could do the full series.
>
> How's that?
>
>
> Thanks,
> pq


I will work on this. Thanks for the constructive comments!