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.
giscanner: rename "colon" to "delimiter"

It serves as a GTK-Doc "field" separator, so delimiter seems
like a better name. This also makes the distinction between the
colon used in property/signal names (which is not a "field"
separator) and the GTK-Doc "field" separator a bit more clear.
giscanner: rename "comment" to "description"

Simply because they are called description fields on GTK-Doc parts...
giscanner: rename AnnotationParser() to GtkDocCommentBlockParser()

Clarify the purpose of what up until now was know as the
AnnotationParser() class, as it does more than just extracting
annotations, it parses the complete GTK-Doc comment block.
giscanner: rename the parse() method to parse_comment_blocks()

We already have a parse_comment_block() method parsing a single
GTK-Doc comment block so it only seems natural to have a plural
parse_comment_blocks() to go along with that.
giscanner: expand parse_comment_block() parameters

Makes it consistent with the parse_comment_blocks() and
_parse_comment_block() methods.
giscanner: use "\s" instead of "[^\S\n\r]"

The original idea was to only match non breaking space, but
there's really no reason to do things differently than gtkdoc-mkdb.
giscanner: always use re.UNICODE mode

should prevent us from running into locale specific issues
wrt what's whitespace, alpha, numeric, etc.
giscanner: define __slots__ on some classes

For example, when creating Gtk-3.0.gir, thousands of instances
of these classes get created. This makes us waste less space
for these instances by not having their __dict__ being created.
giscanner: complete vararg parameter parsing

Normalize deprecated @Varargs [1] and named __VA_ARGS__ [2]
notations in as single location, add tests. Remove special
casing in maintransformer as it is no longer a special case
(tests/warn/unknown-parameter.h passes).

[1] https://git.gnome.org/browse/gtk-doc/commit/gtkdoc-mkdb.in?id=4c9d4db0e264d403b301dad9be1c290134846d03
[1] https://git.gnome.org/browse/gtk-doc/commit/gtkdoc-mkdb.in?id=55c78181d6ae1606bdf7885e9caed70a484127ec
giscanner: give pointer to original comment block...

...when complaining about multiple comment blocks
documenting the same identifier.
giscanner: remove Position.offset()

It's never used...
giscanner: give message.ERROR a purpose

It's not yet being used but will be in the future by
annotationparser.py to signal the difference between
message.WARNING:
    something is wrong but the comment block can still
    be parsed and serialized back into a comment block
    without information being lost
message.ERROR:
    something is wrong and the comment block can *not*
    be parsed and serialized back into a comment block
    without information being lost

Different tools can then act accordingly. Nothing will
change for g-ir-scanner but this will be important for
the GTK-Doc comment block rewriting tool to prevent
extremely broken input leading to even more broken
output...
giscanner: only warn about missing delimiter when necessary

Turns out gtkdoc-mkdb has always accepted identifier parts
with and without a delimiter after the identifier_name field,
so it is safe to only require it when annotations are present or
in other words, when there are actually multiple fields to be
seperated...
giscanner: restore support for 'Return:' and 'Returns value:' tags

Accepted by old version of annotationparser.py and actually
encountered in the wild. Internaly normalize to 'Returns:'.
giscanner: rename DocBlock to GtkDocCommentBlock

and move it downwards after DocTag, DocOptions etc for
easier reading