add examples, tweak documentation