add better docs, fix minor issue