RFR: Add jextract guide

[Maurizio Cimadamore]

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

doc/GUIDE.md line 392:

> 390: ### Function Pointers
> 391: 
> 392: If jextract finds a function pointer type in the header files it parses, it will generate

More directly: `Jextract will generate a separate class for each function pointer type found in the header files it parses.`

doc/GUIDE.md line 420:

> 418: We again have a meta-data accessor for the function descriptor (`descriptor()`). There's
> 419: an `allocate` method that can be used to allocate a new instance of this function pointer,
> 420: who's implementation is implemented by the `fi` functional interface instance. And finally,

Suggestion:

whose implementation is defined by the `fi` functional interface instance. And finally,

doc/GUIDE.md line 448:

> 446: 
> 447: Here we use the lambda `(a, b) -> a * b` as the implementation of the `callback_t` instance
> 448: we create using the call to `allocate`. This method returns an upcall stub like the ones

Suggestion:

we create using `allocate`. This method returns an upcall stub like the ones

doc/GUIDE.md line 449:

> 447: Here we use the lambda `(a, b) -> a * b` as the implementation of the `callback_t` instance
> 448: we create using the call to `allocate`. This method returns an upcall stub like the ones
> 449: returned by the `java.lang.foreign.Linker::upcallStub` method. The `arena` argument denotes

Should there be a link here - like we did for symbol lookup?

doc/GUIDE.md line 451:

> 449: returned by the `java.lang.foreign.Linker::upcallStub` method. The `arena` argument denotes
> 450: the lifetime of the upcall stub, meaning that the upcall stub will be freed when the arena
> 451: is closed (after which the callback instance should no longer be called).

"should not be called" seems to imply that if we call it something bad happens, but we can call it (e.g. it's up to our "goodwill"). "can no longer be called" seems more appropriate?

doc/GUIDE.md line 486:

> 484: `callback_t` instance.
> 485: 
> 486: Jextract generates function pointer classes like the `callback_t` class for function

I know what you mean here - but I wonder if readers will get it w/o some kind of example.

doc/GUIDE.md line 493:

> 491: 
> 492: Jextract handles variadic functions differently from regular functions. Variadic functions
> 493: in C more or less like a template, where the calling convention changes based on the number

Suggestion:

in C behave more or less like a template, where the calling convention changes based on the number

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559178430
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559179645
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559181255
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559181887
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559183287
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559187645
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559188565