DOC: docstring and comment changes

Suggestions from Yarick on PR