added javadoc and finalized utility methods (#21)