add javadoc and rename api methods