some more documentation and comments and a little code clean-up