more documentation and light refactoring