addressed Tills comments and added documentation