lots of documentation and refactoring