Documentation
Some Diplomat backends support --docs, which will generate additional documentation from your Markdown doc comments
$ diplomat-tool cpp cpp/ --docs cpp-docs/
The C++ and JS backends generate Sphinx docs. If using TypeScript, the definition files will automatically come with tsdoc-compatible doc comments.
A limited amount of intra-doc-links are supported: it is possible to link to custom types (but not methods or variants) using [`FooBar`] syntax, like Rust.
Furthermore, you can use #[diplomat::rust_link(path::to::rust::type, Struct)] to autogenerate links for to published docs, which typically show up as a “For more information see <link>” at the bottom of the docs for the given item. Since Diplomat cannot do resolution on other crates, it relies on the rust_link annotation to provide the kind of Rust item or doc page being linked to. An additional compact parameter can be passed in case you wish to provide multiple rust_links that are to be collapsed into a single “For more information see 1, 2, 3” line.
Put together, this might look something like the following:
#![allow(unused)]
fn main() {
#[diplomat::bridge]
mod ffi {
use my_thingy::MyThingy;
/// A Thingy
#[diplomat::rust_link(my_thingy::MyThingy, Struct)]
#[diplomat::opaque]
pub struct Thingy(MyThingy);
#[diplomat::enum_convert(my_thingy::SpeedSetting)]
#[diplomat::rust_link(my_thingy::SpeedSetting, Enum)]
pub enum SpeedSetting {
Fast, Medium, Slow
}
#[diplomat::enum_convert(my_thingy::ThingyStatus)]
#[diplomat::rust_link(my_thingy::ThingyStatus, Enum)]
pub enum ThingyStatus {
Good,
Bad
}
impl Thingy {
/// Make a [`MyThingy`]!
#[diplomat::rust_link(my_thingy::MyThingy::new, FnInStruct)]
pub fn create(speed: SpeedSetting) -> Box<Thingy> {
Box::new(Thingy(Thingy::new(speed.into())))
}
/// Get the status
#[diplomat::rust_link(my_thingy::MyThingy::get_status, FnInStruct)]
pub fn get_status(&self) -> ThingyStatus {
self.0.get_status().into()
}
}
}
}The full list of item kinds recognized by rust_link is:
StructStructFieldEnumEnumVariantEnumVariantFieldTraitFnInStructFnInEnumFnInTraitDefaultFnInTraitFnModConstantAssociatedConstantInEnumAssociatedConstantInTraitAssociatedConstantInStructMacroAssociatedTypeInEnumAssociatedTypeInTraitAssociatedTypeInStructTypedef