refactoring en masse + more jsdoc