further documentation and typos