Minor fix to readme content
Several improvements to code clarity and documentation. Also some minor fixes those uncovered