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

> 779: 
> 780: Please note that other header files included by jextract may also define macro values using
> 781: the `#define` pre-processor directive. Therefore it is often important in which order

There seems to be issues with this sentence. Possible suggestion:

`It is therefore important to notice the order in which header files are processed by a compiler, as feeding header files to jextract in the wrong order may result in weird errors due to missing macro definitions`

doc/GUIDE.md line 808:

> 806: ### Additional clang options
> 807: 
> 808: Users can also specify additional clang compiler options, by creating a file named

Maybe here we should start by saying that `jextract` uses clang to parse C files. And if additional options need to be passed to the clang instance used by jextract...

doc/GUIDE.md line 814:

> 812: ## Other Languages
> 813: 
> 814: As noted in the introduction, jextract currently only supports C header files, but many

Should we say something about many libraries (e.g. libclang) providing a C interop wrapper around their C++ impl?

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559204281
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559205783
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559207077