global refactoring & doc additions