updates to README and some code documentation