Update documentation.

Also removed external documentation (e.g. function parameters) from the
actual code. This avoids duplication. Now only comments pertaining to
implementation subtleties should remain there.