fix issue #223 and add some docs