tidy up lots of comments and make the api more idiomatic