update to actual javadoc comments for api methods