improving the documentation with some examples