Transcription of documentation comments to generated bindings

[jextract at xpple.dev]

Hello,

I have been using jextract for a while now, and my experience has been 
great overall. The only thing that bothered me when using the generated 
bindings was their lack of documentation. Then I thought: would it be 
possible to transcribe the documentation of the symbols in the C header 
file into the generated Java code? Since C and Java have the same 
(mostly, anyways) comment syntax, this could even be done in a super 
naïve way by copying the literal strings. You would look at comment 
tokens that precede the target symbol (ignoring some whitespace perhaps) 
and copy it over.

Looking at the Clang API, it seems they already associate documentation 
comments that belong to a declaration with said declaration. Clang 
attaches a `RawComment` to a `Decl` when the comment is immediately 
before it and separated only by whitespace. This could be used to 
transcribe the comment. Of course, the C documentation string wouldn't 
be in JavaDoc format, but even if it's in Doxygen or any other format, 
it's _much_ better than nothing at all.

Is this something that you guys would be interested to look into? If I 
find the time I could give it a shot, but given my inexperience with 
Clang I'm not sure it would result in the best code :).

Kind regards,


Frederik van der Els

PS: I saw the recent discussion on "jextract cannot generate portable 
code (anymore)" and it's about the exact same issue I reported in March 
last year ("Bindings crash on Windows where they would not before"). 
It's indeed the case that the mismatch is now made explicit by crashing, 
but in my case the C library didn't use any platform dependent types, so 
the type wouldn't have been used anyways. I would love to see a solution 
for this.