Would this not require a Java source parser? I forget how this works in Java world...

I rethought this a bit and I think I have a new proposal, which would take less work and be more generically useful.

Maybe an @:docsOnly annotation which would then apply the documentation to the matching type without compiler conflicts. This would allow for documentation to be applied to a class you otherwise couldn"t modify, such as an extern generated from a Java lib automatically by Haxe. Notably this would be different from writing the extern myself, as I would then have to include undocumented fields, make sure all the types are compatible, fix any compiler errors, etc.

I could then make the program to automatically generate the documented modules from documented Java code using the Doclet API

We actually have a similar situation with our @:coreApi, where target-specific classes such as std/jvm/_std/String.hx receive their documentation from the "core" class std/String.hx. This has always felt pretty hacky though because the compiler has to hide some class paths in order to even locate these files, which are technically shadowed.