Improve and update documentation

 * Tweak documentation in a number of places. Rename a few minor variables.
 * Add brief package level documentation. Closes #221.
 * Fix scaladoc references (no more warnings).