Clean up documentation

[vicng]

Here's what's needed for documentation cleanup:

1. Categorize sections better. Replace "// MARK: - Public" (and "Open") with something more descriptive, as these marks are what show up in the generated jazzy docs.
2. Remove use of self. in comments -- jazzy doesn't link properly when these are encountered.
3. When referencing member of other classes, use the format ClassName.memberName in order for jazzy linking to work properly.
4. [Nit] Make sure each sentence ends with a period.
5. Fix - Throws so that each error type documented is in a sub-bulleted list.