a bit more code cleanup and documentation