RFR: Add jextract guide [v2]

[Jorn Vernee]

On Wed, 10 Apr 2024 09:28:15 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Apply suggestions from code review
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> 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?

Let's use italic, as that's the style we often use in the javadoc as well

> doc/GUIDE.md line 25:
> 
>> 23: ## Running Jextract
>> 24: 
>> 25: A native library typically has an `include` directory which contains all the header files
> 
> Here I wonder if instead of using pseudo name for paths, we should use some more real-looking names, like `/usr/include` and `/usr/lib`, which are common in many NIX systems.

I kind of wanted to hint at the fact that all library packages should have an `include` directory. The `/usr/include` directory can seem like a special NIX system path where libraries are installed, but that's more a quirk of the package manager which chooses to put the headers of all libraries in the same directory.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559472440
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559465175