RFR: Add jextract guide [v6]

[Maurizio Cimadamore]

On Mon, 15 Apr 2024 13:25: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:
> 
>   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.

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

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?

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

doc/GUIDE.md line 307:

> 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
> 307: using `-D` on the command line, not accessor will be generated.

Suggestion:

using `-D` on the command line, no accessor will be generated.

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?)

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.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565821418
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565806681
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565809259
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565810496
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565810263
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565815548
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565816332