added documentation and sanity checking