modify README and annotate with comments