Add comments for auto-generated API docs

[gr2m]

Before a new version of account-client gets released, docs are generated automatically from source code, which currently looks like this:

To make it look better, take https://github.com/hoodiehq/pouchdb-hoodie-api as example. We need to add JSDoc Comments like these: https://github.com/hoodiehq/pouchdb-hoodie-api/blob/master/find-or-add.js#L8-L16

[varjmes]

I think you forgot to copy/paste the example? :)

[gr2m]

@Charlotteis the example is this part here:

/**
 * tries to find object in local database, otherwise creates new one
 * with passed properties.
 *
 * @param  {String|Object} idOrObject   id or object with `.id` property
 * @param  {Object}        [properties] Optional properties if id passed
 *                                      as first option
 * @return {Promise}
 */

It's a special format of JavaScript comments, that follows the conventions of JSDoc. The basic idea is: keep your code & documentation together, to help keeping your docs & sync in place. It's very interesting and I think http://usejsdoc.org/ is worth checking out.

If you like to play with it, add some comments, then run npm run docs locally, and then open /docs/build/index.html

[varjmes]

Cheers!

[florida]

I'd love to take a look this one @Charlotteis !