Rustdoc circular references. Least-bad work-around?

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, 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 -sys crate.

Has anyone else wrestled with this before?


Attribute macros can generate documentation text. You could have a macro that generates a requested set of footnote-style URL definitions, and at least define the base URL in one place, maybe overridable at build time somehow.

(This is just an idea; I haven't looked for prior work on this problem.)

1 Like

My normal approach is to leave the -sys crate as completely bindgen-generated and completely independent of any Rust wrappers that I might write on top of it. I might add some examples to the crate docs, but they'll be showing how you use the raw FFI functions and maybe explain a bit about the library this -sys crate is linking to.

I feel like your -sys crate should be either

  1. An implementation detail that users of your safe wrapper don't need to know about, or
  2. A common crate that is only used by people familiar with the original C library (e.g. clang-sys)... in which case they don't really care about that some error type is returned by your mycrate-rs::MyStruct::my_method

Also, quoting from the naming chapter of the Rust API guidelines:

Crate names should not use -rs or -rust as a suffix or prefix. Every crate is Rust! It serves no purpose to remind users of this constantly.

So you should prefer a naming scheme like clang-sys and clang.

1 Like

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.