lots of documentation, and some dbg tweaks