small refactorings and documentation