Add JSDoc annotations to the public API

[gaearon]

This adds JSDoc annotations to the public API as discussed in #140 and #89.
Comments are welcome!

(This is written against the 1.0 API which is not officially released yet.)

[nstadigs]

You could use @link here
http://usejsdoc.org/tags-inline-link.html

[gaearon]

Good point. For now I'd avoid hardcoding URL because we might move that package to a separate Github organization soon.

[nstadigs]

That's probably wise

[gaearon]

I'll get this in, but comments are still very much appreciated.

The hardest part to understand is probably applyMiddleware but some terminology docs from #140 will help there. Other than that, please let me know if we can rephrase some parts of it for clarity!

[nstadigs]

A good way to document callbacks is to use the @callback tag. This way you can document the @params of the callback function.

[gaearon]

Thanks, I didn't know this! Want to send a PR?

[nstadigs]

Sure! I don't really have time tonight though. Guess I can do it after the merge?

Edit: Oh, its merged already ;)

[gaearon]

Yeah feel free to make a PR against breaking-changes-1.0 branch.