cleanup & sources review
updating documentation (via Sami)