improved documentation with some doctests