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>

I've reviewed the document again. It looks very good, and the structure of the documents strikes me as just right (well done!). I've left picky comments (e.g. 99% review), which I consider optional. I'm ok with the PR being pushed in its current form.

doc/GUIDE.md line 676:

> 674: In the above snippet, note that the load of the `baz` field value on the last line will
> 675: _see_ the update to the `bar` field of the `foo` instance on the line before.
> 676: 

Perhaps we could also add a section (maybe in a followup PR) on fields/globals with array types, as jextract generates extra metadata (e.g. dimensions) and the Java type used for these accesses is MemorySegment (with bulk copy support on `set`)

doc/GUIDE.md line 706:

> 704: ### Preprocessor Definitions
> 705: 
> 706: C header files are processed by a pre-processor by a compiler before they are inspected

I think you mean pre-processor, and remove "by a compiler" ?

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

Marked as reviewed by mcimadamore (Reviewer).

PR Review: https://git.openjdk.org/jextract/pull/231#pullrequestreview-2003056787
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566997489
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566999472