updated readme: better code example, method documentation