In Cargo.toml you can specify [dependencies], [build-dependencies], and [dev-dependencies], but there’s no [doc-dependencies] section, and that occasionally causes me trouble.

How am I supposed to link to crates that are only referenced in documentation? For example:

• comparisons with other, similar crates
• migration guides from deprecated crates
• usage docs that mention non-dependency crates
• linking to items from a feature-gated dependency without having to pass --all-features every time

and so on.

Of course, I could just link directly to docs.rs, like [`HashTable`](https://docs.rs/hashbrown/latest/hashbrown/struct.HashTable.html), but:

• it always points to docs.rs, which is wrong for offline local docs or docs hosted somewhere other than docs.rs
• it isn’t validated against Cargo’s dependency resolution, making broken links more likely
• the syntax is clunky compared to simply writing [`HashTable`] as you would for a normal dependency

The quote crate works around this with use proc_macro2 as syn so it can write syn::Ident in its docs, presumably because syn isn’t among its dependencies. (To be fair, syn depends on quote, so even if [doc-dependencies] existed, using it here would create a circular dependency, so it may cause a problem in this particular case. Still, it shows that doc-only dependencies exist in the real world.)

I’d love to hear your thoughts!

2 posts - 2 participants

Read full topic