Add javadocs to explain contract