improving javadocs and tests