fix examples, clarify some stuff
minor