state.js and state_manager.js documentation audit

resubmitting PR, with a clean merge, has been reviewed and documentation added and updated where necessary.

each file is a separate commit.