more docs and code commenting

- a bit of refactoring of code as well, nothing that will break
something that worked with code from yesterday I think. ;)
- currently tested on win32 only, have to test OSX and Linux