correct grammar in javadoc
add speccing comments to update methods