add documentation for what these variables represent and their invariants