Rustdoc circular references. Least-bad work-around?

help
1

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

Has anyone else wrestled with this before?

Thanks!

2

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
3

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
4

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.