Expanding the PHPDoc comments to clarify concepts

Same as above. Also, we don't track the state, we track the history.