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