various tweaks and add some docs