Accommodation for language-agnostic code snippets in GTK documentation [feature]
The documentation generator for Rust's GTK 4 bindings imports relevant documentation from GTK's C codebase, conveniently consolidating conceptual and API reference documentation in one place. Example here: https://gtk-rs.org/gtk4-rs/stable/latest/docs/gtk4/struct.Label.html
There's one caveat: the code snippets in GTK's codebase are specific to C, and there's currently no reliable mechanism to autoreplace them. Given that people also use GTK in Rust, Python, JavaScript and Vala nowadays, I was wondering: what could be a good way to adapt the documentation to this multilingual reality?
One option could be to annotate the code snippets in the C codebase with unique IDs like so:
/**
* GtkLabel:
*
* The `GtkLabel` widget displays a small amount of text. (..)
*
* Here’s a simple example where the label is inside a button:
*
* ```c[id="inside_button"]
* // Pressing Alt+H will activate this button
* GtkWidget *button = gtk_button_new ();
* GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello");
* gtk_button_set_child (GTK_BUTTON (button), label);
* ```
*/
In doing this, the documentation generator for gtk4-rs could continue tracking the upstream C documentation, replace the inside_button
block with a custom-written Rust snippet stored in the gtk4-rs codebase, and publish the result.
Would you be open to accommodating the documentation needs of Rust language bindings? If so, how would you prefer to do it?