or you could even take it a step further, and convert markdown into bbcode so that it meshes better with the rust system.

This would be the way to go. We could start simple, even supporting formats like code, bold or italics would already help a lot.

If I remember correctly, /// text doc-comments should be visible as #[doc="text"] attributes, so they could be picked up by #[godot_api].

Yeah converting basic markdown isnt that hard, it just takes a couple regexes.
^{i just noticed that my code there doesnt use [codeblock] :v
actually i think [codeblock] is a bbcode extension, so i cant be blamed}

The annotations and such would be slightly more difficult, iirc rust doc uses [Struct] and [Struct::property] which would need to be translated to [Struct] and [method Struct.property] || [method property].

Oh nice!

One thing to keep in mind is that proc-macros are a heavy burden on compile time, and regex replacement can be relatively expensive, especially if it's done "poorly" (i.e. each regex match replaces the entire doc-string, causing new allocations and copying). Likely not an issue for small games, this could affect someone with a larger number of documented classes/methods/properties. Would need to be measured though.

Just in case if things slow down, at least it should be (default) disabled in debug build. My reasoning is that docs isn't very useful in prototyping stage, and if one wants to release their addons/games it's nice to have docs for end user.

We do that in gdnative for async and serde, but I'm not sure if doc-generation is "advanced" or "expensive" enough to warrant extra opt-in from the user. Ideally we get a performant implementation, so this isn't an issue in the first place.

we could maybe use https://crates.io/crates/rustdoc-json for help with parsing the docs similar to rustdoc, however it does rely on the currently unstable rustdoc JSON backend.

there isn't a way to do this yet in gdextension, there is a draft PR for it though godotengine/godot#75415

Passing new PR in this topi, as it seems to be accepted and basically stopped only from 4.2 only because it was in feature-freeze. Most probably it will come in 4.3 release, so we could begin to prepare for it.

godotengine/godot#83747

The PR StatisMike mentioned is merged, so this issue should be unblocked now