godot-rust / godot-rust/gdext

Import Godot docs for builtin types

Open
#584 7 comments 1 reaction 0 assignees View on GitHub
c: core documentation feature
Dominant language
Rust
Stars
5.2k
Forks
312
Avg merge
12h 59m
Merged PRs (30d)
9

Description

We should not manually write documentation for builtin types like `Vector3`, `Quaternion`, `Callable`, ... -- except in cases where the Rust API differs from Godot's. Otherwise, it would require us to copy-paste large swaths of Godot's docs, only for it to become outdated when upstream changes.

Instead, can automate it by pre-generating documentation in `godot-codegen` and importing it on demand:
```rs
// Generated code
macro_rules! godot_builtin_doc {
(Quaternion.spherical_cubic_interpolate) => {
"\n\nSome imported docs from Godot."
};
// all the stuff
}
```

```rs
impl Quaternion {
/// A manually written first part of the doc.
#[doc = godot_builtin_doc!(Quaternion.spherical_cubic_interpolate)]
pub fn spherical_cubic_interpolate() {
...
}
}
```

rustdoc output:

![grafik](https://github.com/godot-rust/gdext/assets/708488/ecf64294-8d80-403f-bac1-a4badf0ff536)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.