This commit looks somewhat bigger than it is because I moved some comments
around so we can have longer comments for the constructors. The most important
change is the documentation of the `QGoalReason` invariant on 'GoalChoice'.

This commit doesn't change any actual code.