some javadoc and renames to aid clarity