updated docs for new code. please advise where it can be improved or is unclear!