Updated docs to reflect new functionality

I've updated the docs to reflect the changes in functionality and added a big BACKWARDS COMPAT warning.

I've also written a long step-by-step cookbook: Promises::Cookbook::GentleIntro which I think provides all the info I needed when I started learning about promises.

With this commit, I'd say we're almost ready to release a new version. I'd like it if you were to cast an eye over the docs and cookbooks first.  Perhaps there is stuff that you want to remove or change?