fixing docs and an in-line comment based on review