add some documentation and corresponding little changes in the code