RFR: Add jextract guide [v5]

[Jorn Vernee]

On Fri, 12 Apr 2024 13:49:21 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Phrasing
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 211:
> 
>> 209: // mylib.h
>> 210: 
>> 211: int bar;
> 
> Maybe mention what happens if the definition includes an assignment, `int bar = 4;`, if it matters.

For jextract it doesn't matter

> doc/GUIDE.md line 358:
> 
>> 356: 
>> 357:     for (int i = 0; i < arrLen; i++) {
>> 358:         MemorySegment element = Point.asSlice(point, i);
> 
> Never used this method, but I assume it should be `asSlice(points, i)`.

Good catch!

> doc/GUIDE.md line 456:
> 
>> 454: try (Arena arena = Arena.ofConfined()) {
>> 455:     MemorySegment cb = callback_t.allocate((a, b) -> a * b, arena);
>> 456:     int result = call_me_back(cb);
> 
> Where is `call_me_back` defined?

It's defined in the C file in the snippet above.

> doc/GUIDE.md line 618:
> 
>> 616: 
>> 617: C allows variable declarations to have an inline anonymous type. Jextract handles in
>> 618: particular cases where a struct's field has an inline type specially. For instance, if we
> 
> "Jextract handles in particular cases where a struct's field has an inline type specially."
> 
> I don't understand this sentence. Does Jextract handle nested types only when a struct's field has an inline type?

C doesn't allow other kinds of nested types, so yeah

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565748513
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565750938
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565752183
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565755721