RFR: Add jextract guide [v12]

[Nir Lisker]

On Mon, 15 Apr 2024 23:01:12 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.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update doc/GUIDE.md
>   
>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

Looks very good. Left some minor comments. Can be integrated after they are resolved.

README.md line 5:

> 3: `jextract` is a tool which mechanically generates Java bindings from a native library headers. This tools leverages the [clang C API](https://clang.llvm.org/doxygen/group__CINDEX.html) in order to parse the headers associated with a given native library, and the generated Java bindings build upon the [Foreign Function & Memory API](https://openjdk.java.net/jeps/454). The `jextract` tool was originally developed in the context of [Project Panama](https://openjdk.java.net/projects/panama/) (and then made available in the Project Panama [Early Access binaries](https://jdk.java.net/panama/)).
> 4: 
> 5: :bulb: For instruction on how to use the jextract tool, please refer to the guide [here](doc/GUIDE.md)

Period at the end.

doc/GUIDE.md line 55:

> 53:   through `--output`)
> 54: - `--library mylib` tells jextract that the generated bindings should load the library
> 55:   called `mylib`. (The section on [library loading](#library-loading) discusses how is done)

"how is done" -> "how it's done."

doc/GUIDE.md line 59:

> 57: Note that specifying the wrong header file to jextract may result in errors during parsing.
> 58: Please consult the documentation of the library in question about which header file
> 59: should be included. This is also the header files that should be passed to jextract. If

These sentences mix plural and singular header file(s).

doc/GUIDE.md line 266:

> 264: using `-D` on the command line, no accessor will be generated.
> 265: 
> 266: ### Structs & Unions

This section follows an example using a struct. If there's no difference whatsoever compared to a union, this is fine. Otherwise, I will mention in the example where things might differ.

doc/GUIDE.md line 312:

> 310:     public static MemorySegment reinterpret(MemorySegment addr, long elementCount,
> 311:             Arena arena, Consumer<MemorySegment> cleanup) { ... } // 6
> 312: }

I noticed that some of these methods are `final` and some aren't. Is this on purpose in jextract (why?), or just here?

doc/GUIDE.md line 739:

> 737: name is then mapped to a platform dependent name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)).
> 738: This means, for instance, that on Linux, when specifying `--library mylib`, the bindings will
> 739: try to load `libmylib.so` using the OS-specific library loading mechanism on Linux, which

`libmylib.so` -> not `mylib.so`?

doc/GUIDE.md line 896:

> 894: 
> 895: Jextract uses an embedded clang compiler (through libclang) to parse header files. Users
> 896: can also specify additional clang compiler options, by creating a file named

"options," -> "options"

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

PR Review: https://git.openjdk.org/jextract/pull/231#pullrequestreview-2002311013
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566522599
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566523022
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566525138
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566544393
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566542910
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566560650
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566562931