Add javadocs to make contract more clear