Improve Parser documentation

[alamb]

• While reviewing Improve parsing performance by reducing token cloning #1587 and preparing to improve documentation more it occurs to me the Parser struct could be documented better (especially given the large number of parse_* type methods that make it a bit confusing to navigate

I thought it would help to add some more overview information as well as internals

[iffyio]

LGTM!

[alamb]

Thanks @iffyio