Document potentially surprising behaviour and add tests to cover these cases.

It seems that relative links to the generated `.html` files doesn't work
anymore, so I've replaced them with either `doc` or `mod` references.

Previously the parser documentation did not include warnings and
exceptions. This rearranges things to cleanly separate out functions,
classes and exceptions / warnings, and adds the warnings to the
documentation.

Fixes several misspellings, typos and styling errors (e.g. github ->
GitHub) in the comments and documentation.