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

> 133: ### Builtin Type Layouts
> 134: 
> 135: For every jextract run, regardless of the contents of the library header files, jextract

I'm not sure it's clear where these layouts definitions are introduced. I think the text should say that these are appended to the main header class.

doc/GUIDE.md line 253:

> 251: Note that the enum constants are exposed as top-level methods, rather than being nested
> 252: inside a class called `MY_ENUM`, or through the use of a Java `enum`. This translation
> 253: strategy mimics C's behavior of enum constants being accessible as a top-level declaration

There's another reason as well for not using enums - which is that, in C, you can use bitwise operations to denote enum sets - e.g. `RED | GREEN` (and other more crazy stuff), which would not be possible using Java enums. At its core, a C enum is just a glorified int.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559163217
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559168129