I have a
-sys crate, and it exposes some structs and enums that are mirrors of the C
.h file, like a sys crate should. And it documents those items like all crates should. I also have an
-rs crate that re-exports some of those items.
The problem comes up because I want to provide helpful notes in the
-sys crate's docs that reference items in the
-rs crate. e.g. "This error is returned by [mycrate-rs::MyStruct::my_method] when something bad happens."
Bonus if I could include example source with doc tests, but that's probably asking too much.
This issue (Figure out a way to link to downstream crates · Issue #74481 · rust-lang/rust · GitHub) tracks the core issue, but looks like it's a long way from any resolution. So I'm asking about the least-bad work-arounds.
The idea to document the re-export instead of the original item would be good, but doesn't allow for documenting methods of a
struct or individual items of an
enum, so that's out.
I could use the full URL syntax, and point to the documentation up on https://docs.rs, but that is bad because it won't necessarily reflect the correct version of the crate, not to mention requiring a network connection even if the docs directory is local.
A variant on that above idea would be possible if rustdoc allowed for some kind of "BaseURL" syntax, e.g.
[mycrate-rs::MyStruct::my_method](BaseURL/mycrate-rs/*/mycrate-rs/struct.MyStruct.html) Is something like this possible?
Of course I also hand-waved over the wildcard version matching. But if I had to hard-code the version that might not be so bad.
And then there is the "Sledgehammer" method of just duplicating the whole darn
-sys crate inside of the
-rs crate. But that seems to kinda defeat the whole purpose of a
Has anyone else wrestled with this before?