various code refactorings, completion of the doc