Improve README and Documentation

[yakovkhalinsky]

The documentation and the README needs a bit of improvement.

[ablankenship10]

Do the promises still work (or only work?) the way as described in the README?

I am using the promises like so that seems to work also:

b2.functionName(payload)
    .then(callback)
    .catch(errorCallback);

EDIT: looks like this is somewhat explained in the 0.9.x to 1.0.x upgrade section.

[yakovkhalinsky]

Should do, if the promise ever resolves with an error(rejection).

The second arg in the .then(arg1, arg1) if a reject is ever called in the promise. It's of course optional.

The .catch() is also a feature of the promise, not something I've added in the README.

Might need a more comprehensive example at the top of the README probably to explain this.

[odensc]

Relevant: #53

[yakovkhalinsky]

I might look at making some nicer docs using GH pages so we can get a proper list of functions, and also add async/await as well as traditional Promise.then().catch()

Or should we just be documenting examples with async/await?

[cbess]

I'd say just using asyn/await covers our basis

[odensc]

Agreed - I think we should just use async/await for examples.

[Bimman2021]

this documentation is very poor. despite my years of using api. i still struggle to get things done. probably drop use case examples