Fully document API using comments and @doc tags [JIRA: CLIENTS-563]

[nerophon]

A customer has noted that it is standard practice to properly document APIs, with specification of both success and all possible failure cases. This way, applications using the client will be easier to write, more complete, and more robust.

This is quite easy to do in Erlang using @doc tags above function definitions.

Going hand in hand with this, every function, whether part of the API or not, should have full type specs of expected returns using -type syntax, and pass dialyzer checks. This makes the documentation easier as well, and effectively proves the specifications by static analysis.

Inspired by Zendesk ticket #11805.

[hazen]

Fantastic suggestion, @nerophon. I've noticed a dearth in comments in parts of the code.

[sata]

@nerophon: Will this also take #224 into consideration?