RFC: Links to Rust items in documentation text

[steveklabnik]

Issue by huonw
Tuesday Oct 15, 2013 at 07:57 GMT

For earlier discussion, see rust-lang/rust#9864

This issue was labelled with: A-rustdoc, I-enhancement in the Rust repository

---

(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.

[Mange]

I'd be interested in seeing this RFC get some more activity, now that 1.0 is far behind us. I hope it's okay to resurrect old RFCs like this. This is my first time, so I apologize if this is not the way to go.

---

Regarding the placeholder syntax.

Perhaps overloading normal Markdown links is the way to go, as to not introduce anything non-standard to the Markdown syntax? One could attach special meaning to a new ref: scheme for the URLs that resolve to documentation for a type.

See [`FooEnum`](ref:FooEnum)'s [`Bar`][bar] variant.

[bar]: ref:FooEnum::Bar

If this is too much work for references, perhaps a shortcut could be made like this:

See [`FooEnum`]'s [`Bar`][FooEnum::Bar] variant.

where the compiler would auto-insert references to links with backticks on them, resulting in the following complete markdown:

See [`FooEnum`]'s [`Bar`][FooEnum::Bar] variant.

[FooEnum]: ref:FooEnum
[FooEnum::Bar]: ref:FooEnum::Bar

I personally think that would be a bad idea for a first go at this as it might paint us into a corner later, but putting it out there anyway.

[sfackler]

@Mange https://github.com/rust-lang/rfcs/blob/master/text/1946-intra-rustdoc-links.md

[Mange]

Thank you. I didn't realize that this wasn't the newest RFC on the matter. I see that #1946 is merged now. Does that mean that this RFC should be closed?

[sfackler]

Yep, I believe it should be!