Add guidance about linking to external crates

[sunjay]

The Documentation page should add information about linking to external types/crates. Right now we have the following section:

Prose contains hyperlinks to relevant things (C-LINK)

Links to methods within the same type usually look like this:

[`serialize_struct`]: #method.serialize_struct

Links to other types usually look like this:

[`Deserialize`]: trait.Deserialize.html

Links may also point to a parent or child module:

[`Value`]: ../enum.Value.html
[`DeserializeOwned`]: de/trait.DeserializeOwned.html

This guideline is officially recommended by RFC 1574 under the heading "Link
all the things".

This talks about linking to your own types, but what about for types/functions/etc. in other crates? What is the best practice for those? What does a link need to look like so docs.rs will resolve the link correctly? Most people use docs.rs to host their docs, so it needs to work well there.

Should people use absolute links? For example:

[`specs::Component`]: https://docs.rs/specs/*/specs/trait.Component.html

If so, what should the version be? I put * in the link above but another valid choice would be the current version my crate is using. Is there a way to do this without having to update version numbers all the time whenever I upgrade a dependency? What (if anything) does rustdoc provide in this regard?

Absolute links are a little less convenient when developing locally. I think many crate authors actually use relative links like the following because this works when you run cargo doc:

[`specs::Component`]: ../specs/trait.Component.html

Information about all of this would be a great addition to the guidelines because I think crate authors think about this stuff and if we're going to ask them to "Link all the things" we should at provide enough guidance for them to do that.

[Enet4]

This is worth prioritizing, as we are taking the risk of making poor decisions in the documentation process. In emphasis:

think many crate authors actually use relative links like the following because this works when you run cargo doc

This is true, but it does not work once uploaded to docs.rs. Broken documentation links ensue to those reading the docs online.

But at the same time, I don't feel very eager to hardcode an absolute link to docs.rs, since not all crates have adopted this service. Perhaps some tooling improvements are needed before we think about guidance?

[jonhoo]

This kind of advice would also be great for crates that use cargo-readme to generate their README files, as relative links there break.

[jyn514]

I would also like to see this. I've been using cargo +nightly doc to link to crates that are in scope, but there's not a way to do this without an extern crate mycrate or use mycrate::sometype in the code itself. See bytecodealliance/cranelift#1038 (comment)

[spazm]

What is the preferred way to link to a std crate?

1. Link all the things section uses a relative link : [`String`]: ../string/struct.String.html
2. The example uses an absolute link to doc.rust-lang.org : [`Option<T>`]: http://doc.rust-lang.org/std/option/enum.Option.html.

I think item 1 is only for use inside std lib docs, where String would be a relative crate?

[spazm]

As a document author, I would like to specify intent and let the tool figure out the links.
Computers will be far better at this type of conversion than I will be.

Perhaps a custom scheme (e.g module:// or crate://) could be used? This would have semantic meaning before conversion. Rustdoc would pre-processed to output absolute links for markdown.

Would the complexity of the url format ar docs.rs / doc.rust-lang.org be too difficult to use in this simple of a format e.g. as the URLs include extra keywords. trait.*.html vs enum.*.html

• crate://std.foo.Foo => http://doc.rust-lang.org/std/foo/Foo
• crate://std.foo.Foo::try_foo => http://doc.rust-lang.org/std/foo/Foo#try_foo
• `crate://some-thing => http://docs.rs/some-thing/*/some-thing

Notes:

1. Relatedly/prior_art: in POD (Plain Old Documentation), link format treats links without a scheme for intra- and inter- module linking. They are specially processed into full links in the conversion to concrete documentation output of html, manpage, etc. This allows the document writer to express intent and let the tool figure out the links.

• "mod" => link to module mod
• "/sec" => link to section sec in this module
• "mod/sec" => link to section sec in module mode

2. POD link format may well predate http or at least popularity of http. The L<...> tag started without schemes and later added URI support with schemes.

3. Later tools added the ability to pre-pre-process the documentation, to allow clearer intent for the developer and more uniform output for the user. (e.g. PodWeaver, Dist::Zilla::Plugin::PodWeaver).

[jyn514]

I think this is fixed by rust-lang/rust#74430, which will be stable tomorrow in 1.48. The documentation should say to use intra-doc links for your dependencies.

Note that this doesn't work for crates you don't depend on (rust-lang/rust#74481), in that case I think it does make sense to recommend docs.rs.

[jyn514]

This kind of advice would also be great for crates that use cargo-readme to generate their README files, as relative links there break.

I don't think there's a great solution for this in general, since intra-doc links use rust scopes and crates don't know their own names (so crate would work inside but break outside, and vice-versa for the name of the crate). Maybe cargo-readme could hack around it by including the documentation in lib.rs and rendering that? But I think that's a separate problem from what the API guideline should recommend.

[tyranron]

@jyn514 the main problem we're hitting this at the moment is documenting proc-macro = true crates. For example I have crate foo with a trait Bar. I do want to use foo::Bar reference in docs of derive(Bar) macro to explain its usage, but I cannot do that, because foo-codegen crate cannot be a dependency of foo crate (because it's vice versa).

I've tried to use foo as dev-dependency of foo-codegen crate, but the intra-doc links feature still complains about unexisting item 😕, it doesn't see such imports.

Another problem with docs.rs that very often crates in closed codebases are not published there.

[bjorn3]

If you add a doc comment to the re-export in foo, it is prepended to the doc comment on the #[proc_macro_derive] function in foo-codegen when showing the docs for foo. You could move the doc comments to the re-exports and keep the proc macros in foo-codegen undocumented.

//- foo-codegen/src/lib.rs
#[proc_macro_derive]
pub fn Bar(/*...*/) -> /*...*/ { /*...*/ }

//- foo/src/lib.rs
/// Doc comment containing [`foo::Bar`].
pub use foo_codegen::Bar;

[jyn514]

If you add a doc comment to the re-export in foo, it is prepended to the doc comment on the #[proc_macro_derive] function in foo-codegen when showing the docs for foo.

I spent a long time getting the scoping for this to work 😅 I don't remember if it's in 1.48 but it will definitely be in 1.49.
rust-lang/rust#77254

[tyranron]

@bjorn3 @jyn514 nice to know, thanks!

But it still would be nice to have an ability to intra-doc-link dev-dependenices in docs. As code generation logic happens to be quite untrivial in many situations, we usually write docs to it, which explain and guide through the implementation. Those are private docs, but having an ability in them to refer the crate (codegen is implemented for) would be nice.

[jyn514]

See the discussion in rust-lang/rust#74481, this requires fundamental changes to how cargo compiles crates. I agree it would be nice to have but it's not clear how.