giscanner: refactoring: rename options to annotations

and stop confusing them with array, out, scope and transfer options
which where confusingly also names options...
giscanner: refactoring: rename comment to description

Besause that's what they are called.
giscanner: refactoring: rename DocBlock to GtkDocBlock

Because GTK-Doc comment blocks are the only kind of
comment blocks we're interested in.
giscanner: refactoring: clarify PART_* and SUBJECT_* constants

The PART_* and SUBJECT_* constants are only ever used to
track state in _parse_comment_block(). This is unlike the
TAG_*, ANN_* and OPT_* constants which are used to match
the input GTK-Doc comment block text.

Changing these to simple ints makes the difference clear.
giscanner: refactoring: order TAG_* constants alphabetically

Makes it easier to locate things
giscanner: fix varargs detection in maintransformer

Because AnnotationParser.parse() normalizes the different
kinds of GTK-Doc varargs notations to simply '...'.
giscanner: use constants to refer to annotations

Analogous to commit #b04e0df15a67b1159752615941527023bd781a39
giscanner: fix parsing named parameters in variadic macros

For variadic macros it is allowed to name the __VAR_ARGS__,
as described in http://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html

This patch follows the now deprecated behavior of gtkdoc-mkdb,
which renamed the argument to "..." and thus silently dropped
the argument name.
giscanner: deprecate (in-out) in favor of (inout)
giscanner: start testing GtkDocBlock.to_gtk_doc() output

fixing a couple of minor issues along the way.
giscanner: calculate line numbers up front
giscanner: remove reference cycles from DocTag, DocOption

Storing a reference to the parent object in not needed anyway
as these are not used anywhere to begin with...
giscanner: make it impossible to set non-existant attributes

helps a bit during development
giscanner: break out parameter and tag to_gtk_doc methods

into specialized subclasses
tests: don't show the default assertEquals message on Python 3

When assertEquals fails, Python 3 prints a default message
clobbering the carefully crafted diff output we print afterwards.
tests: add missing (allow-none) test
tests: add missing @returns tests
tests: add GTK-Doc syntax test

This tests a confusing but real (and actually found "out there")
case of mixing GTK-Doc comment lines starting with and without a *.
giscanner: add support for broken "Return:" and "Returns value:" tags

The old annotationparser code accepted these without complaint so
add them to the list of tags to transform into a normal "Returns:"
tag. Fixes a couple of real life cases "out there".
giscanner: rstrip description text

but not when the line only contains spaces because that
would break GTK-Doc's paragraph notation.