normalize names, add javadocs