some fixes and more documentation
resolve merge conflicts