clarify docs - closes gh-45