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

> 2: 
> 3: The jextract tool parses header (.h) files of native libraries, and generates Java code,
> 4: called 'bindings', which  use the Foreign Function and Memory API (FFM API) under the hood,

maybe add a link for FFM to the final JEP, so that readers who want to know more can do so?

doc/GUIDE.md line 4:

> 2: 
> 3: The jextract tool parses header (.h) files of native libraries, and generates Java code,
> 4: called 'bindings', which  use the Foreign Function and Memory API (FFM API) under the hood,

There's several words in the documents which are wrapped in single quotes. Should we use italic here, or bold?

doc/GUIDE.md line 15:

> 13: returned by a lookup, and construct `MemoryLayout` instances for the structs they want to access.
> 14: Jextract aims to automate many of these steps, so that a client can instead immediately start
> 15: using a native library they are interested in.

I suggest using `the native library` (because it's the one they are interested in). Also consider using plural (e.g. the native libraries).

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559133910
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559135755
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559138201