Improve docstrings in parser.py
This MR adds usage examples to the docstrings in
parser.py. This makes the parser API reference a bit more useful for people who don't have the full context on how the parser actually works.
This MR also fixes the parameter documentation for some of these classes, which previously didn't match the actual method signature.
Closes #283 (closed)