giscanner: refactor annotation validation

- annotations on the identifier (formerly g-i specific tags) have
  never been validated before, so fix this
- removes duplicate validation code from GtkDocTag and GtkDocParameter
- remove repeated validation code doing the same thing as
  annotationparser from maintransformer...
giscanner: merge _parse_comment_block() into parse_comment_block()
giscanner: accept different forms of line breaks
giscanner: store code before and after comment block

so we can later use them to re-write source files containing
broken GTK-Doc comment blocks where /** is preceded by and/or
*/ is followed by code...
giscanner: fix description field storage in .gir files

GTK-Doc description fields for tags can contain multiple lines and
even multiple paragraphs. Whitespace cannot be preserved in XML
attributes, so we move the "deprecated" description text into
a "<doc-deprecated />" element right next to where we already have
the "<doc />" element. Keep the "deprecated" attribute around for
backwards compatibility though, but set its value to "1" (analogous
to the "writable", "contruct", etc attributes) if the annotated
symbol is marked as deprecated.

While at it, add <doc-version /> and <doc-stability /> which
was not yet available in the .gir files...

This takes care of the "Since:", "Stability:" and "Deprecated:"
GTK-Doc tags. Nothing needs to be done for the "Returns:" tag as
as we already write a "<doc />" child element on "<return-value />".
giscanner: store indentation before the '*' of each line
giscanner: better lineno handling

No need to enumerate the comment lines list as we already receive
the lineno of the very first line as a parameter. Simply increment
that one when looping over the comment lines list.
giscanner: improve state tracking
giscanner: honor line and paragraph breaks in description fields

GTK-Doc parameter description fields are allowed to span
multiple lines, tag description fields are allowed to span
multiple lines and paragraphs. A tool fixing/rewriting
GTK-Doc comment blocks in source files would need to have
description fields parsed and stored (almost) exactly as
they appear in the source file.
giscanner: use proper terminology
giscanner: make some warnings errors

GTK-Doc comment block fixer tool will refuse to rewrite source
files that generated errors (indicating a source->parse tree->source
would result in information being lost), but will happily continue
on warnings (which do not result in information being lost).
giscanner: add missing tests
giscanner: refactor GTK-Doc comment block serialization
giscanner: don't generate synthetic names for '...' parameter

tests/warn/unkown-parameter.h:41 still passes with this...
giscanner: Fix GtkDocBlock.position...

... so it points to the start of the GTK-Doc comment
block instead of the position of the identifier field.
giscanner: return namedtuples where appropriate

makes _parse_annotations() and _parse_fields() callers slightly
more readable
giscanner: make Annotated.attributes an OrderedDict

annotationparser.py already stores attributes in a mapping so
it makes little sense using a list of tuples (suggesting
multiple duplicate keys would be allowed) on the ast side.
tests: sync with GTK-Doc test suite @ 1846fc7e904f6f56b74c366d205d6bb946eac17e
docs: Update Makefile.am
docs: document some annotationparser.py hacking hints

https://bugzilla.gnome.org/show_bug.cgi?id=688897