make state properties more consistent and update docs