README: fix the Tools section a bit
tests: Update misc/pep8.py to 1.4.6

Updated from:
https://raw.github.com/jcrocholl/pep8/1.4.6/pep8.py
tests: make parsed2tree() and expected2tree() methods of TestCommentBlock()
tests: put create_tests() below TestCommentBlock()

closer to __main__, where it's actually used...
tests: rename <commentblock> element to <input>

We'll start testing parser warning/error messages and
serialized output later on so this will make it easier to
see what's parser input and output...
tests: put <docblock> element inside a <parser> element

The <parser> element can then hold both the expected
<docblock> parse tree and the warning/error messages
emitted by the parser in a future <messages> child
element.
tests: validate GTK-Doc test files

This is more of a handy developer tool than something
that is always expected to be executed as part of the
test suite, so we don't add a hard dependency on xmllint.

https://bugzilla.gnome.org/show_bug.cgi?id=688897
tests: remove manual validation code

We're already validating input .xml files so no need
to duplicate this...
tests: compare matched groups when testing re's
tests: fix warning tests message sorting...

... by using the actual line numbers instead of sorting
the whole expected/emitted string. The latter is wrong as
for example tests/warn/annotationparser.h line 109
got sorted before line 120 which got sorted before
line 12.
tests: test emitted GTK-Doc parser warning messages
tests: fix diff output

Empty lines do get removed or added sometimes, so make sure we see
those in our diff output.
tests: move GTK-Doc comment block warning tests

It makes sense to let test_parser.py check everything which
is focused purely on testing GTK-Doc comment blocks
(ie annotationparser.py functionality).
giscanner: remove dead code

Last call sites where removed in 36aa515f1036978ced8d4ffb808260844f7229e0
about 3 years ago.
giscanner: fix typo
giscanner: improve inline docs
giscanner: tiny MainTransformer cleanup
giscanner: fix parameter name check

It's been impossible to have a TAG_RETURNS in GTK-Doc comment
block parameters for a long while now as we transform those
into valid tags in parse_comment_block()...
giscanner: reindent re documentation
giscanner: rename "options" to "annotations"

Makes it easier to understand the difference between
an annotation and an option, which are written as
"(annotation option1=value1 option2=value2 ...)" in
GTK-Doc comment blocks.