Document promises in promises.markdown.

[benjamingr]

When discussing promises in io.js in IRC. @Fishrock123 suggested we consider a promises.markdown file explaining how to use promises in io, explain the rationale and approaches to the rejection event hooks added to process and common io.js related issues (working with a promise API and so on).

• Should such a page exist?
• What information should such a page include?
• Where should it be linked to?

[benjamingr]

In my opinion such a page would be really useful. I think it should include information about working with promises in io.js as an ES6 feature, explaining the different issues

• Userland implementation vs native promises.
• Converting the core APIs and userbased APIs to promises automatically.
• When you cannot use promises (for example, they do not replace streams and they do not replace event emitters).
• Handling errors.
• Global hooks with process events. How to use them and what are the different approaches.

I'm still not sure where it should be linked to from or where it belongs since this is a language feature and not a core API - I do think that such a page would be really useful somewhere.

[vkurchatkin]

-1. Not much to say (yet)

[micnic]

-1, promises are described quite well in the wild
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

[piscisaureus]

As long as we only provide docs on node-specific APIs I would think we shouldn't do this.

However, I find that this is not a great policy. It's really hard to explain to new users that we document the Buffer object and Url module but not Promise or Math. Maybe it's possible to re-publish (javascript documentation (from mdn) on our website.

I guess this is a question for the @iojs/website team.

[indexzero]

I agree with @piscisaureus on this for the same reason. If we include it at all we should be including it as part of a larger ES6 documentation page which would more or less link to various MDN pages.

[sam-github]

-1 on this, promises are not special, nor async, now how to use closures. io.js docs should focus on io.js.

[benjamingr]

Good, I think we have a consensus. So closing.

@piscisaureus I like your idea - you might want to open a separate issue :)