document how the buffer works