fix typos, update docs, clarify wrong example