Add documentation and some clarifying comments.

Use a consistent commenting style with a period at the end and put
documentation in headers where possible.
Enable -Og optimization by default.

Supposed to be optimizations that do not interfere with debugging.