Revert "Revert "Add self documented comments - ready for version 1.0.1""

This reverts commit 79af93c56c906ed07fdb187c877272bb3d036add.