some refactoring and documentation improvements