The javadocs should include sample code for commonly used methods. The javadocs should link to the docs/manual to the conceptual pages like all findAndModify/Remove methods should link to the "findAndModify" docs page.