update javadoc - describe how each method response