updated usage examples with better comments