RFR: Add guide section about array types [v2]

[Jorn Vernee]

On Tue, 16 Apr 2024 16:28:53 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with three additional commits since the last revision:
>> 
>>  - review comments
>>  - Update doc/GUIDE.md
>>    
>>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>>  - Update doc/GUIDE.md
>>    
>>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 644:
> 
>> 642:   This method returns a `long[]` where each element represents the length of a dimension
>> 643:   of the array type. For instance, in the example `FOO_ARRAY` has a two dimension, whose
>> 644:   lengths are `3` and `5`, so the `FOO_ARRAY$dimensions` method will return a `long[]`
> 
> instead of "whose lengths are", I think it's better:
> "has two dimensions - 3 and 5 respectively - ..."
> (e.g. let's avoid talking about dimensions' length, which I don't think is very well defined)

Yeah, good call.

> doc/GUIDE.md line 646:
> 
>> 644:   lengths are `3` and `5`, so the `FOO_ARRAY$dimensions` method will return a `long[]`
>> 645:   with two elements whose values are `3` and `5` in that order.
>> 646: 3. a getter and setter pair for the array variable. Note that the getter replaces the usual
> 
> Should we start from this?

I maintained the source order, but we can re-order (I did that for the function example as well). Getters/setters seem more important, so let's put them at the start.

-------------

PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567665433
PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567666115