Document how to use high level and low level APIs

[jvz]

The primary feature a good cryptographic library provides for making things easy to use and hard to misuse is documentation; without documentation, the only users who can understand these types of libraries are cryptographers and security engineers who already know how to use the low level primitives and have little need for a library like this. In particular, various vocabulary must be defined, use cases explained (e.g., when do you need non-repudiation versus just authenticity, using context metadata/AAD for simulating type information, identities, and session state, how to handle key exchange, authentication, etc.), and examples provided. For the high level API, these should be both documented in javadoc (for more API-specific concerns) as well as in the wiki or future website with an appropriate narrative. Links to established standards (and perhaps even papers) are expected, but links are not sufficient for the documentation; make sure to summarize any important information.

Some established cryptography projects offer a lot of documentation. See libsodium docs and Themis docs for some decent examples of higher level documentation.

Lower level APIs (e.g., crypto primitives) can be documented via javadoc. While it may be nice to mention some of the math going on in the background (e.g., prime order groups and permutations), this may get overly technical which may also end up incorrect without accompanying proofs.