documentation for the 'source description' states
filling in some todos
filling in the section on state transitions
filling in some more sections