RFR: Add jextract guide [v6]

[Jorn Vernee]

On Mon, 15 Apr 2024 13:41:51 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 79:
> 
>> 77: [libclang](https://clang.llvm.org/docs/LibClang.html) native library in order to parse C sources).
>> 78: 
>> 79: ### Preprocessor Definitions
> 
> IMHO both this and the following section is not important enough to appear so early in the document. If we went straight to "Using The Code Generated By Jextract" we would not lose anything - then after that section, we can provide more details about various aspects/options.

Not sure... I know what you mean, but knowing how to run the generated code seems fairly important. It seems that that is something someone might want to try out after the first example. Unfortunately, this requires understanding library loading, which is fairly complex.

Also, the comment about feeding jextract the right header file seems pretty important since user may run into errors when running jextract otherwise (we've seen many questions about that, e.g. when someone tries to extract some arbitrary Windows header instead of `Windows.h`).

But also, I realized that this guide may not just be used by first-time readers, but also as a reference by more experienced users, in which case it seems nice to have info about command line flags mostly in one place.

> doc/GUIDE.md line 848:
> 
>> 846: ## Unsupported Features
>> 847: 
>> 848: There are several elements for which jextract can not generate bindings:
> 
> element seems a bit vague, maybe "C program elements" could be better, although in this cases I suppose most developers will think about the term "features". Consider just having a bullet list and skip the first statement (after all, the title says it all). Note also the list is provided here:
> https://jdk.java.net/jextract/
> (maybe we should drop it from there in the future, to avoid duplication?)

Yeah, we probably just want to link to the guide from the download page

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565837436
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565838811