further internal docs and cleanup