Avoid misuse in error handling in apollo-parser

[goto-bus-stop]

Note: this is just about the implementation of the apollo-parser crate, and not relevant for end users.

There's currently an internal kind-of footgun in apollo-parser: if you are parsing something in a loop, and hit an error, and use p.err(), the parser does not advance. That means you can get into an infinite loop. This is partially addressed by having p.peek_while(), which we will have to be diligent about in reviews. But it's still something to keep in mind that is not that clear when reading a PR.

In general, it would be good to have some documented approach for the difference between p.err() and p.err_and_pop(). When should one be used over the other?

This is spun off from https://github.com/apollographql/apollo-rs/pull/828#pullrequestreview-1872134384