documentation updated with examples