fixing strange update not valid issue in debug builds and adding some documentation to it