chg: refactor, work on documentation, etc.

* also remove some debug output
* remove some outdated TODOs
* overwork documentation (but only a bit)