more documentation and some readability/syntax changes