correct inline docs to be complete, consistent and accurate