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
Add giscanner package documentation

Using Sphinx [1] markup for now. We eventually might want
to add GTK-Doc support for python and dogfood g-ir-doctool
on this package.

[1] De facto standard Python documentaton tool: http://sphinx-doc.org

https://bugzilla.gnome.org/show_bug.cgi?id=688897
giscanner: write virtual method instance parameter docs to .gir file
giscanner: complain about text before the ' * '

Makes our GTK-Doc comment block rewriting tool halt on
such issues, requireing user intervention instead of writing
back even more bogus data.
giscanner: fix c0e748e1cdf8cf0803266f94c3c5ad154df504a8

When encountering /**/ in the source, parse_gtk_doc_comment()
would be executed (due to the /** part starting a GTK-Doc
comment block) and would happily consume the / and everything
up until the next comment block was closed or EOF, thus
consuming a whole block of C code...

Encoutered in the wild here:
https://git.gnome.org/browse/clutter-gst/tree/clutter-gst/clutter-gst-player.c?id=03f0d8f48bd7f60e582e6185cb73a07038e8d55d#n1926