more refactoring and documentation updates