JSDoc needs better JSDoc comments

[hegemonic]

JSDoc's API documentation is woefully deficient, the irony of which does not escape me. I made the problem much worse by adding dozens of // TODO: docs comments during my JSDoc 3.3 blitz through lib/jsdoc/src.

We should at least have proper documentation for the methods exported by each module. We should also make sure that the docs reflect someone's (my?) idea of JSDoc best practices (for example, "put an asterisk at the start of each line").

[Zearin]

I can do some work on this.