add javadoc + reorder methods