RFR: Add guide section about array types

[Maurizio Cimadamore]

On Tue, 16 Apr 2024 16:18:32 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> The current guide is missing a section discussing the special handling of array types, for which jextract generates a `$dimensions()` accessor, and indexed getters and setters.
> 
> This PR adds a section to the guide discussing this. I've put it at the end of the "Using The Code Generated By Jextract" section. I've put it before the section on nested types though, since it's a little more important I think.

doc/GUIDE.md line 641:

> 639: 1. a layout accessor, just like we have for a regular variable, but note that the return
> 640:   type is [`SequenceLayout`].
> 641: 2. a `$dimensions` meta-deta accessor, which returns the _dimensions_ of the array type.

Suggestion:

2. a `$dimensions` meta-data accessor, which returns the _dimensions_ of the array type.

doc/GUIDE.md line 643:

> 641: 2. a `$dimensions` meta-deta accessor, which returns the _dimensions_ of the array type.
> 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

Suggestion:

  of the array type. For instance, in the example `FOO_ARRAY` has two dimensions, whose

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)

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?

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

PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567651344
PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567651832
PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567653123
PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567648387