This is offered in the spirit of highlighting a “TODO” for the docs rather than just complaining 
Trying to learn Rust by reading source code and the docs has been a bit of a frustrating experience for me so far. There seem to be many constructs in source files that use complex syntax that I can’t decipher using the docs. Probably because the syntax was always in flux before so it wasn’t documented thoroughly, but as part of 1.0 hopefully the manual, guide, and Rust by Example can be updated to explain the syntax better.
I wish I had been keeping track of examples better, but here’s a couple of things I’ve noticed lately…
// `<T>` Must precede the type to remain generic
impl <T> GenericTup<T> {}
I think the docs would benefit from an explanation of why you have to write out the parametric type(s) twice like this. I.e., what does the first represent and what does the second represent? Are they ever different? RbE (in the example above) just says you “must” do it without explaining it.
<<Self as SliceExt>::Item>
This is some kind of magic incantation that lets you refer to the type of the elements in a slice, but how does it work? AFAICT “casts” (as) and recursion in type specs are undocumented, but that seems relatively straightforward. But where is that Item coming from? SliceExt doesn’t seem to have an item called Item, at least by my look at the docs.
(The whole "slices magically get methods from SliceExt" thing is another can of worms. 
I actually think something like “This trait is magically applied to all slices” would be a marginally better summary of SliceExt than “Allocating extension methods for slices”, which doesn’t mean anything to me.)
Thanks for listening,
Matt