add comments and clean up the validation and the code
add some more examples