some documenting and refactoring