RFR: Add jextract guide [v12]

[Maurizio Cimadamore]

On Mon, 15 Apr 2024 23:01:12 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.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update doc/GUIDE.md
>   
>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

doc/GUIDE.md line 236:

> 234: ```
> 235: 
> 236: Jextract will generate a set of simple getter methods to access the constant values of the

Nit: maybe omit the word `set` - e.g. just "generate simple getter methods...". Seeing "set" so close to "getter" might be confusing.

doc/GUIDE.md line 262:

> 260: through the FFM API.
> 261: 
> 262: Note that for macros, jextract only generates an accessor when it sees a macro definition,

Feels like here we need a link to the preprocessor section

doc/GUIDE.md line 376:

> 374: ```
> 375: 
> 376: The pointer that is returned by the corresponding method that jextract generates

Consider streamlining this by saying "The pointer that is returned by new_point does not have..."

doc/GUIDE.md line 378:

> 376: The pointer that is returned by the corresponding method that jextract generates
> 377: for this function does not have the correct bounds or lifetime associated with it.
> 378: These things are not possible to figure out automatically (for instance, a pointer

Suggestion:

These properties cannot be inferred: for instance, a pointer...

doc/GUIDE.md line 426:

> 424: ```
> 425: 
> 426: We again have a meta-data accessor for the function descriptor (`descriptor()`). There's

Maybe here using numbers in the code and a numbered list would be (a) more consistent and (b) more readable

doc/GUIDE.md line 682:

> 680: 
> 681: - Certain C types bigger than 64 bits (e.g. `long double` on Linux).
> 682: - Function-like macros (as mentioned in the [section on constants](#constants-macros--enums))

I wonder if here we got the reference backwards - e.g. perhaps the section on constants should just say that function-like macros are not supported and point here, then here we could say what workarounds could be used in more details?

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566978455
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566983513
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566987029
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566987831
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566990577
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566981579