more documentation and refactoring