add JSDoc annotations across the codebase

[ckolderup]

this will also be a good opportunity to audit the codebase and probably spot some weird artifacts from early development.