[PATCH docs] Clarify the wire format array specification

[Pekka Paalanen]

On Fri, 27 Sep 2013 17:11:47 -0500
Micah Nordland <mpnordland at gmail.com> wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> On 09/27/2013 05:02 PM, Bill Spitzak wrote:
> > I think it is confusing to call this an "array", rather than
> > perhaps a "block" or something.
> > 
> > When I read the documentation I thought the array consisted of N
> > pieces of data in wire format, not N bytes.
> 
> That was my initial impression as well, perhaps instead of changing
> the name, the spec should be changed to the length being the number of
> items and contents of the array required to be one of the protocol's
> defined data types.

You can't really do that. The size in *bytes* must be available to
the generic protocol parser in libwayland, and if you change the
size to be number-of-items, then you also need to define the size
of one item. In other words, instead of receiving one number, you
receive another number and multiply it with a third number you have to
get from somewhere.

You can't require one specific item type for all arrays, because
the array structure is supposed to be able to hold any (custom)
type.

On the wire the array type is not too different from a string, but
the API of libwayland is different.

And also, you can't change any of that without breaking the world,
even if the change was unanimuously to the better. We're stuck with
it.


Thanks,
pq