fix @returns to be @return for yuidocs

see example at http://yui.github.io/yuidoc/syntax/#return
Merge pull request #158 from mikepmunroe/change-returns-to-return-in-yuidocs

fix @returns to be @return for yuidocs
fix 154 by documenting .cast
incorporate first pass feedback from @stefanpenner
change wording to -The resulting promise-
add grunt docs task

add grunt-contrib-yuidoc to grunt config
output api documentation to docs/ when grunt docs is run
Merge pull request #160 from mikepmunroe/add-yuidoc-grunt-task

add grunt docs task
Notes on how to use deferred
Merge pull request #141 from sandstrom/patch-1

Notes on how to use deferred
Fix typo in new Deferred writeup
Merge pull request #161 from dgeb/patch-1

Fix typo in new Deferred writeup
update .cast docs with resolve comparison info from @domenic

@domenic added notes in domenic/promises-unwrapping#86
those notes comparing promise.cast with promise.resolve have been
added to .cast docs
add @domenics latest suggestions

RSVP.promise -> RSVP.promise.cast
set then to code
additional text for clarification
Merge pull request #159 from mikepmunroe/154/document-cast

fix 154 by documenting .cast
fix all examples to conform with yuidoc example syntax

remove all markdown code syntax for replacement with yuidoc
example indenting (4 spaces)
the markdown syntax was not generating code blocks correctly
Merge pull request #162 from mikepmunroe/api-examples-to-follow-yuidoc-syntax

fix all examples to conform with yuidoc example syntax
fix case in cast documentation
revert back to github markdown style code examples, so they are compatible with ember's website.

Hopefully we can bring this back in the future.
Adds named function for promise callbacks

[Related PR](https://github.com/emberjs/ember.js/pull/3876).
remove fail, as catch is what the spec defines.

es3 users can use that `promise['catch']` syntax