Any crates using RFC 1946, rustdoc links based on rust paths?

1

I just found out about this newish feature and want to get a sense of how ready it is for release of public crates. Are any crates released that use it already? I'm hoping to see it working all the way through docs.rs but can't find an example.

If you also missed it, here is a quick summary of this rustdoc feature, which I believe was introduced in rust 1.25, though it didn't make any release notes I can find, nor it is mentioned in the rust book. Where as we used to have to do things like the following for intra-rustdoc links:

/// types: [`BodySink`](struct.BodySink.html)
/// functions: [`from_file`](#method-from_file)

We can now do the following, for simple implicit links:

/// types: [`BodySink`]
/// functions: [`BodyImage::from_file`]

Or when necessary to disambiguate, as per normal rust paths:

/// types: [`BodySink`](body_image::BodySink)
/// functions: [`from_file`](BodyImage::from_file)

In addition to much more intuitive syntax, unresolvable link paths are treated as errors, which is potentially a great help to avoid broken links. See above linked tracking issue and the original RFC for much more detail.

Also, anyone tested how or if this will play with the 2018 Edition, path clarity changes? My current intuition is to update links as part of upgrades to the 2018 edition, though I should also try that myself on a recent nightly.

4 Likes
2

Here is what I've found as to the readiness of this feature for release use:

Current docs.rs is using a one-off, pre-1.28 version, where cargo doc only supports a sub-set of the feature. There is an effort underway to update/replace docs.rs which should have a complete implementation as per current nightly rust. See onur/docs.rs#233.

There is no stable release yet with the complete feature: 1.28.0 and 1.29.2 are incomplete. Perhaps the 1.30 release will have it. If you expect cargo doc to work locally for users on your minimal supported rust version, then you will obviously need to wait.

3

(Onur's github repo seems to have no issues, but #233 on the rust-lang-nursery seems to match your description.)

4

Thanks for the re-link. The original repo was apparently transferred to rust-lang-nursery as a step in the salvage efforts. The state of this rustdoc feature obviously takes a back seat to Docs.rs is Down.

5

Oh dear, that sounds like a complex operation is going on :slight_smile:

6