add some docs, minor re-arrangements