docs + extended examples