a little refactoring and documentation