hoodiehq/documentation — pull request #57 by boennemann (2014-08-19 15:36:07+00:00)
Title: Leave out .then in code examples, use only .done & .fail

> What you really have to recognized here is that there is a mayor difference between the methods `then` and `done`. While `done` suggests that you can handle all the retrieved objects with it, actually it is `then` where `findAll` will deliver your data to. `done` on the other hand gets called when all other `then` calls have been passed. Yes you can utilize this mechanism to work with your data in several steps.

There is more to `.then` than just being called before the .done callbacks. I see `.done` / `.fail` / `.progress` as the public API that all users should use per default. `.then` is for advanced users that know what they are doing. And as they know that we return promises, they know it already.