API docs for promises

API docs for promises

@coffeemug -- could you take a look at it?