cleaning up variable names a bit and adding some inline docs