Improved javadoc and parameter naming

/cc @demobox