After finishing the next release (yeah it's coming soon) I'll be focusing on brushing up the reference docs for a bit. Apart from making them current, I'd like to brush up the format a bit too. So I can use some inspiration.
What are your favorite docs sites and why?
Ye, I agree with the ones you mentioned: a complete overview of the entire library in the sidebar + comprehensive specifications for each entry. I'd point you to the mapbox api reference https://www.mapbox.com/mapbox.js/api/v2.1.0/ They are well structured, with great explanations & good examples
...that would be cool!
The jQuery docs have an interactive demo for each argument in the function. When I was starting out, I found that amazing.
google's material design for the use of animated examples http://www.google.com/design/spec/animation/responsive-interaction.html
I like docs that let you toy with each little thing as you learn it
I always loved the PHP Manual with it's user comments below. Makes for a great collection of user-contributed examples.