[PATCH docs] Clarify the wire format array specification

[Bill Spitzak]

On 09/28/2013 12:09 AM, Pekka Paalanen wrote:
> 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.

I understand that, what I meant was that the documentation is confusing 
by using the word "array". I thought it was an array of items and was 
looking around, trying to figure out where the type of the items was 
defined, and just figured I had not understood the documentation.

I think the *documentation* should be changed to use the word "block" or 
"data" or something, as long as it does not use "array". Not the api.