rustdoc: Include (or link to) methods "inherited" through auto-deref

[mbrubeck]

Based on new-user questions on IRC, many users are confused by the fact that this is valid code:

let v: Vec<int> = vec![1,2,3];
let i = v.head();

even though the Vec<T> documentation does not include a method named head. This is because head is actually a method on type [T], and Vec<T> implements Deref<[T]>.

More generally, it's not easy (1) to look at the documentation for a given type and see all the methods that are callable on values of that type, or (2) to look at a piece of code and figure out where to find the documentation for a given method.

This could be fixed by listing "T methods callable via dereference" on the documentation page for a any type that implements Deref<T>. (This is similar to how systems like JavaDoc list "methods inherited from BaseClass" in the docs for any class that extends BaseClass.)

[tomjakubowski]

Using the Vec<T> example, should this include trait impls/methods on [T] as well? I suppose inherent and trait implementations/methods available through dereference could be separated as they are in the ordinary method list today.

[kmcallister]

Nominating for 1.0-stable.

[pnkfelix]

It would be sweet if this were fixed. But its not a 1.0 blocker. Assigning P-high.

[gsingh93]

This is incredibly confusing for people new to the language. Hopefully this gets implemented soon (I'd be happy to help if I could get some direction).

[tomjakubowski]

I've made a couple prototype implementations of this feature in rustdoc and discovered where the pain points are for me. For 1.0, I think the best thing would be a more conservative implementation of this feature, designed to accommodate the most common uses of Deref found in the standard library. This feature could always be made more accomodating later to support more exotic deref types, of course.

We absolutely need to be able to inline methods for these very commonly used, and often asked about, standard library deref pairs:

• str methods on String (&self only, because there is no DerefMut impl)
• [T] methods on Vec<T> (&self and &mut self)

Another nice to have would be additional sections on the Vec docs for methods available on, say, Vec<u8>, via autoderef to &[u8] and &mut [u8].

Other, more exotic Deref impls using where clauses and fancy generics and whatnot can be supported later.

[steveklabnik]

nominating for 1.0, while I don't think it should be a blocker, it's a really, really bad polish issue, at least as bad as #23511

[pnkfelix]

Assigning to @alexcrichton for 1.0.