more documentation and some fixes