updated docs and new convenience constructor