I disagree with the framing here and think it is biased. I can comment more when back at my computer (which will be later tonight).

@domenic biased against what? I tried to keep it as simple as possible and using the least promise terminology. Is your issue with the terminology or are you looking for a more 'pro-promise' sentiment?

I think it should simply cover how every philosophy is implemented and their pros and cons in an unbiased way, for example not saying that something is rare but saying that in some programming styles this will result in false positives.

There doesn't seem to be a way to document either event in isolation without being biased actually.

Any usage example of unhandledRejection event in isolation is biased towards instant logging/throwing philosophy, because what else can you do in there if you use that event alone?

And rejectionHandled is only needed if you buy into the growing and shrinking list of rejections philosophy so documenting its usage is going to be biased towards that obviously..

@petkaantonov which is why this PR after the update due to @domenic 's comment shows both patterns. The unhandledRejection event is demonstrated in isolation and then in the rejectionHandled event the shrinking list idea is explained (paraphrasing @domenic's own words) and demonstrated. I think the current balance is ok - anything you'd change?

Your update doesn't include any example usage of the 'unhandledRejection' event, it just says that an event will be fired but you don't show example code handling it.

@petkaantonov from the doc:

Here is an example that logs every unhandled rejection to the console:

process.on('unhandledRejection', function(reason, p){
    console.log("Possibly Unhandled Rejection at: Promise ", p, " reason: ", reason);
    // application specific logging, throwing an error, or other logic here
});

OK. I've left extensive comments on ways to improve this, because I am passionate about this subject getting good docs treatment. HOWEVER, @benjamingr's edits since my original comment have addressed the bias I perceived, and so I think if there's a release imminent it's fine to merge this as-is without necessarily implementing my changes. We should do them eventually though since they're good changes :)

Events in markdown should use single quotes, for example 'rejectionHandled'.

The example uses an odd mix of double and single quotes for strings, I'd suggest single quotes everywhere.

Markdown should be wrapped, like all other text lines in io.js.

Thanks @domenic and @sam-github I've updated the PR with all the advice and the formatting issues included except for the FileHandle example since I've found it a bit controversial (the API format itself) and I think we can come up with a more concise one. I've pretty much merged all the proposed changes by domenic (good terminology remarks) - the only thing I didn't change there explicitly was "error handler" to "rejection handler" because I find the terminology more approachable to people who are new to promises.

Rebased.

OK, I want to get a release out today and this is going to get merged to make that happen. If anybody disagrees with the language please suggest changes, otherwise perhaps reserve them for a future PR.