Assorted documentation and formatting cleanups

> Why don't we encode these comments directly into the code by using types

Sure thing.

> I'm not a big fun of comments in general

I agree that the types should speak for themselves where possible, but comments are still important for stuff that cannot be encoded in the type system. We do need to get more disciplined on this front. This will help new contributors getting started on the project.