update docstring
add an example
add ValidatedTrait in the documentation
update changelog