I think the main problem with the docs right now is that most people looking at them aren't just new to the API, but also new to the lang - it can be quite hard to navigate them if you don't know much about the type system and how APIs may be composed using Rust's various facilities. That is obvious, I guess, but it doesn't stop people from trying.
Some way to conflate the two types of docs might be cool. For example, if there were high-level examples of commonly used API patterns in the std lib ("we use traits in this fashion here to achieve the following goals"), the docs could embed links to them as factoids ("this is an application of <this pattern>"). Heck, even just a ? button next to the "Traits" header linking to the book's Traits section would probably help some folks.
Linking to rust-guidelines in some way to back up the design of various APIs might be cool, too.
(Don't want to be the guy to crash Happy Day with more requests, so I'll just add: Many thanks for all your work, Rust has been tickling my brain in enjoyable ways like nothing else this year.)
We had a long, hard think about it. We had a fairly significant amount of Markdown, the tooling was already written, and on a more personal note, I like the idea of reStructuredText, but I _hate_ writing it. If we'd have overwhelming reason to switch, we still would have, but basically, that's why: not enough reason to overcome momentum.
Some way to conflate the two types of docs might be cool. For example, if there were high-level examples of commonly used API patterns in the std lib ("we use traits in this fashion here to achieve the following goals"), the docs could embed links to them as factoids ("this is an application of <this pattern>"). Heck, even just a ? button next to the "Traits" header linking to the book's Traits section would probably help some folks.
Linking to rust-guidelines in some way to back up the design of various APIs might be cool, too.
(Don't want to be the guy to crash Happy Day with more requests, so I'll just add: Many thanks for all your work, Rust has been tickling my brain in enjoyable ways like nothing else this year.)