updated naming, docstrings and prose docs for Issues #187, #199 and #12