$mdSidenav: change to promise-based API, add documentation

[ajoslin]

$mdSidenav('left').then(function(leftNav) { leftNav.close(); });

[rschmukler]

@ajoslin what's the thought on a promise based API here? There's nothing async about the get operation, so perhaps this is just extra abstraction?

[ThomasBurleson]

@rschmukler - just like the $componentRegistry, there are use cases were a user is querying for the component BEFORE it is ready/registered. A the promise-based API keeps the API consistent with $mdDialog, $componentRegistry, etc. Should we discuss this offline?

[dmackerman]

This would be super useful. In our app, we load a lot of "detail" information in a Sidenav, and we utilize ui-router's onEnter and onExit callbacks to hide/show sidenavs. This would ensure that the Sidenav is available before we show anything. 👍

@rschmukler: it could be async in the case that the component isn't ready, as other directives/templates have to be compiled before it if it's being included in a sub-state, etc.

[AllenSH12]

+1 for at least the docs, my guess is a lot of people (myself included) primarily want to use the sidenav as it works in mobile apps, click an option and it goes away. It's possible to figure out from the repo but takes some work.

@rschmukler @ThomasBurleson @ajoslin if I can be of any assistance documenting or being a guinea pig please ask.