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 257:

> 255: 
> 256: Not all types of macros are supported though. Only macros that have a primitive numerical
> 257: value, a string, or a pointer type are supported. Most notably, function-like macros are

Several people wonder what to do when dealing with a library that is heavy in its use of function-like macros. There's two strategies here - the first is to replicate the code in the function-like macro in Java, using FFM. The second is to create a small C library which turns the function-like macro into a proper function, so that it can be used from FFM. Not sure we want to add this detail here (or maybe in an appendix).

doc/GUIDE.md line 309:

> 307: ```
> 308: 
> 309: There's a getter and setter for each field of the struct (1), which takes a pointer to a struct

I see you didn't use bullet lists much, but I wonder if one would be helpful here instead of a single long para? Perhaps even a numbered list, where the number refers to the comment in the code?

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559170731
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559172937