RFC: Links to Rust items in documentation text

[huonw]

(The syntax should be decided on. <<<>>> is just a bad-by-design placeholder so that it gets changed.)

/// Foo bar. See also <<<baz>>> or <<<qux::foo>>>
pub fn foo() { }

pub struct Thing {
    /// Read by <<<Trait.read_x>>>
    x: int
}

pub trait Trait {
    /// Something something <<<Thing.x>>>
    fn use_x(&self) {}
}

impl Thing {
    /// For use with <<<Thing.gadgets>>>
    pub fn stuff() -> Thing {}

    /// Get things from <<<Thing::stuff>>>
    pub fn gadgets(&self) {}
}

pub enum Enum {
    /// Is different to <<<VariantB>>>
    VariantA,
    /// Not the same as <<<VariantA>>>
    VariantB
}

/// Blah blah <<<self::Enum>>>
pub fn bar() {}

/// Designed for use with <<<::std::option::Option>>>
/// or <<<::another::crate::Struct.field>>>
pub mod qux {
    /// Maybe <<<super::foo>> is relevant too.
    pub fn foo() {}
}

The text in <<<...>>> would be interpreted as a module-relative path (unless prefixed by :: which makes it crate-relative), since I imagine intra-module links are the most common. And each <<<foo::bar>>> would get replaced by either [bar](rustdoc generated link) or [foo::bar](rustdoc generated link) or something (possibly/preferably linking each component of the path in the latter case).

Issues

I'm very unsure about:

• how to write a link static methods on traits/types in a way that can be implemented easily (since the use proposal below doesn't work with use Trait::static_method or with types either);
• distinguishing between methods <<<foo.method>>> and fields <<<foo.field>>>.

Other tools

• Haddock: 'Foo.Bar'
• Sphinx: :py:mod:foo``
• Javadoc: {@link #foo(type, type)}
• RDoc: {text here][rdoc-ref:Foo::Bar]

(These aren't necessarily correct, and I'm sure there are many many more possible syntaxes.)

Implementation

One possibility for implementation by rustdoc just throwing the contents of each <<<>>> into a use statement in the current module like (from the top of the example above):

use unique_name_1 = self::bar;
use unique_name_2 = self::qux::foo;
use unique_name_3 = self::Trait;
use unique_name_4 = self::Thing;
// ...
use unique_name_10 = std::option::Option;
use unique_name_11 = another::crate::Struct;

// inside qux
use unique_name_1 = super::foo;

where unique_name_... would be designed in so that it can never occur in user code (e.g. containing non-ident characters). After running resolve, rustdoc could go in an extract the value of each name. Notably, the optional .<ident> gets stripped, and has to be extracted by the rustdoc code itself, and this would also mean that documentation could result in a compile error if any of these links doesn't resolve properly (which is quite sensible IMO).

A nicer method would be if resolve could be queried for individual items after running as a whole.

[chris-morgan]

Notable also is that Sphinx is not just :py:mod:foo. You'd be setting the default domain to py (or in our case, rust), so it'd end up just :mod:foo, :trait:foo::Bar, etc.

Sphinx cross-references also have the ability to control what is displayed; following the normal Sphinx conventions:

• :trait:foo::Bar would have the link text foo::Bar;
• :trait:!foo::Bar would be foo::Bar but have no hyperlink;
• :trait:~foo::Bar would be just Bar;
• :trait:Baz <foo::Bar> would be Baz (but a link to the trait foo::Bar);

I've said it before in relatively-private, and I'll say it again here: I believe strongly that using reStructuredText and Sphinx would be a better plan than using the Markdown systems currently in place. Partly, this is because of my very strong belief that reStructuredText is the distinctly superior language (it's actually designed with this sort of extensibility in mind, whereas Markdown is just a tangled mess, lousily specified), and partly because constraining ourselves to purely automatically generated documentation is manifestly a bad plan, yet that seems to be the direction rustdoc is heading at present (I would love to be wrong on this point—tell me I am!). Writing custom documentation is very important; the Django docs (incidentally managed with Sphinx) are a very good example. (Sphinx would also provide the tools for producing the entirely automated API documentation which would, of course, still be desirable.)

For the next few weeks I don't have time, but I'm certainly interested in writing a Rust domain for Sphinx to demonstrate why it's better.

reStructuredText is also good for this customisability as it makes it buttery-smooth to make more syntax extensions, e.g. you could trivially add a role to make links to GitHub issues like :ghi:9864. I'm sure we'd find a great many things where we could beneficially use reStructuredText's power.

[emberian]

Visiting for triage. Still relevant, still not super easy to implement.

[steveklabnik]

I'm pulling a massive triage effort to get us ready for 1.0. As part of this, I'm moving stuff that's wishlist-like to the RFCs repo, as that's where major new things should get discussed/prioritized.

This issue has been moved to the RFCs repo: rust-lang/rfcs#792