Issue/770 rewrite comments

Fix #770 - substantial re-write of comments