RFR: Add jextract guide [v6]

[Jorn Vernee]

On Mon, 15 Apr 2024 13:32:21 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   review comments
>
> doc/GUIDE.md line 147:
> 
>> 145: some examples of how to use the generated Java code.
>> 146: 
>> 147: Most of the methods that jextract generates are `static`, and are designed to be imported
> 
> Uhm - I think the paras you moved fitted nicely in this introductory section

I think they could go in either section? But, this way, we can discuss the `--header-class-name` option in the section about running, which I think makes more sense.

> doc/GUIDE.md line 226:
> 
>> 224: First and foremost, there is a static wrapper method that is generated that can be used to
>> 225: call the C function (1). Besides that, there are also several accessors that return
>> 226: additional meta-data for the method: the function's address, represented as a
> 
> Should we use a numbered list here too?

I don't think it's possible to start a markdown list at `2`, but I will try

> doc/GUIDE.md line 306:
> 
>> 304: 
>> 305: Note that for macros, jextract only generates an accessor when it sees a macro definition,
>> 306: like the one in the example, in the header files it parses. When a macro is only defined
> 
> Suggestion:
> 
> like the one in the example, in the header files it parses. When a macro is defined

`only` is relevant here. If a macro is defined using `#define` _and_ on the command line, jextract will generate an accessor.

> doc/GUIDE.md line 869:
> 
>> 867:   WARNING: Skipping Foo (type Declared(Foo) is not supported)
>> 868:   ```
>> 869: 
> 
> Bitfields missing?
> Also, support for primitive types > 64 bits.

Bitfields is there. I'll add an item for types > 64 bits

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565813726
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565814932
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565816756
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565820708