giscanner: flesh out annotation parsing and storage

- remove annotations regex, restore proper parens parsing
- drop weird DocOption() storage class and use lists/dicts
  as appropriate
- make GtkDocAnnotations a simple OrderedDict subclass instead
  of a weird hybrid dict/list storage class
- Deprecate Attribute: tag, replace with (attributes) annotation
  on the identifier
giscanner: deprecate GObject-Introspection GTK-Doc tags

After discussing a different issue with the GTK-Doc maintainers,
we learned that our g-i specific top level tags should never have
existed in the first place. The prefered notation for annotations
that apply to the identifier should be written on the identifier
line, for example like what we already do with (skip).

As a result, this patch deprecates g-i specific top level tags and
implements them as annotations on the identifier instead but still
keeps support for malformed comment blocks using g-i specific top
level tags.

This means that all annotated code "out there" will continue to work
just fine with this version of g-i, but when a developer decides to
fix deprecation warnings in his/her comment blocks, the dependency
on g-i needs to be raised to a version that contains at least this
patch. #676133

https://bugzilla.gnome.org/show_bug.cgi?id=676133
giscanner: give parameters their own storage class
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.