more commenting and readme clarifications