some docs, and some improvements