Transcription of documentation comments to generated bindings

[Maurizio Cimadamore]

Hi,
at some point we considered doing something for comments. We even tried 
interfacing with Clang API, but then realized it was just for 
Doxigen-style comments. While this allows good integration with 
jextract, we found that almost all the libraries we looked at in our 
experiments were _not_ using Doxigen comments. For that reason we 
decided to sit on it (and work on other priorities at the time).

I think now would be a good time to reopen that discussion. Clang has a 
relatively rich API -- for each "cursor" it gives you the position in 
the original header. So it might be possible even to scrape the header 
file for information, and copy and past any comment-like line into the 
generated output -- although that might be significantly more complex 
that reading Doxigen comments using the API.

So, in a way, the question we should ask ourselves is -- what 
constitutes a comment? What kind of comments do we want jextract to 
support? Would developers feel Doxigen support is a glass half-empty, or 
half-full?

(Having said all this, given Clang has a nice API to get Doxigen stuff, 
at least not dropping that info on the floor feels to me like a good 
starting point -- we could always do more later if we feel it's important).

Cheers
Maurizio


On 21/01/2026 13:46, jextract at xpple.dev wrote:
> 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.