series of fixes and improvements/ a bit more commenting