giscanner: fix string formatting tuples

During review Colin Walters mentioned:

"""
One thing I should probably explain is my habit of *always* passing a
tuple for %.  The reason is pretty simple...a long time ago I had an
error handler that did:  print "unexpected data: %s" % foo.  And I'd
changed the type of "foo" from a string to a tuple at some point.
But this obviously caused "print" to fail because it was expecting
multiple format strings.

Basically always using tuples is safer in case you change the type
of a variable to a tuple.
"""

This fixes violations of this rule introduced up until now.
giscanner: remove unused variables and imports
giscanner: prefer "except X as e" over "except X, e"

It's more readable and as an added bonus Python 3 compatible.
giscanner: don't shadow built-in 'type' symbol

use the documented __exit__ signature instead
giscanner: use SqlAlchemy's OrderedDict implementation

g-ir-scanner can be a bit on the slow side. While true we
now do a bit more work parsing GTK-Doc comment blocks and
more is still to come, one of the biggest hotspots besides
what's going on in _giscanner.SourceScanner() comes from
the OrderedDict implementations we have been using.

For example, time needed to build Gtk-3.0.gir on a relatively
slow machine using "python2 -m cProfile -o $prefix/bin/g-ir-scanner ...":

1) Our original DictMixin sublass:
     92,79867 seconds
2) Python's collections.OrderedDict class:
     88,65786 seconds
3) Larosa/Foord implementation from http://www.voidspace.org.uk/python/odict.html :
     71,64323 seconds
4) SqlAlchemy's implementation:
     66,12449 seconds

Looks like we have a clear winner with the SqlAclchemy
implementation, which comes in at around 20 seconds
without profiling on the same machine. Not bad.
giscanner: fix broken xml:whitespace attributes in .gir files

The XML specification clearly states it's xml:space
http://www.w3.org/TR/xml/#sec-white-space

https://bugzilla.gnome.org/show_bug.cgi?id=628739
giscanner: make _pass_fixup_hidden_fields() more readable
giscanner: make _pass_read_annotations2() more readable

_apply_annotations2_function() is only ever called by
_pass_read_annotations2() so there's no need to go and
hide what's being done behind an extra method call.

Also change the 'if not something; return' into a more
readable 'if something: do something'...
giscanner: emit 'incorrect number of parameters in comment block' warning

instead of silently ignoring parameter names on signals when the
number of parameters doesn't match our expectations.
docs: document some annotationparser.py hacking hints
giscanner: deprecate top level g-i specific GTK-Doc tags.

Rationale
---------

The first wave of improvements on AnnotationParser intended
to fix bug http://bugzilla.gnome.org/show_bug.cgi?id=672254
(multiline descriptions on tags not working correctly, polluting
the comment block description instead) had an unforeseen side
effect reported in bug http://bugzilla.gnome.org/show_bug.cgi?id=674658.

Analyzing this problem we found that even though comment blocks
having g-i specific tags before the comment block description
are technically malformed, the old annotationparser code happily
accepted these without complaint. During this analysis, a secondary
bug report (http://bugzilla.gnome.org/show_bug.cgi?id=676133)
was filed with the GTK-Doc project because it was found that the
same malformed tags did not result in the expected html output.

After discussing this 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 and at
the same time adds support for malformed comment blocks still
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.

Overview of changes
-------------------

1) giscanner/annotationparser.py and giscanner/maintransformer.py
   have been adjusted to deprecate g-i specific top level tags
   and now implement these in terms of annotations on the identifier.
   The Attributes: tag and it's replacement (attributes) annotation
   continue to be broken (regression introduced in commit
   182fdfec261f36fa095484352b9b834861036907), which will be
   addressed in a followup patch.

2) AnnotationParser().parse_options() has learned to correctly parse
   multiple closing parentheses, which is for example required for the
   new syntax in tests/scanner/annotationparser/gi/annotation_type.xml:
   * AnnotationObject:hash-table: (type GLib.HashTable(utf8,gint8))

3) comment blocks in tests/*.c and tests/*.h had to be adjusted as
   these tests are not allowed to emit warnings. As a result, these
   test cases now no longer use g-i specific top level tags but
   annotations on the identifier instead.

https://bugzilla.gnome.org/show_bug.cgi?id=688897
https://bugzilla.gnome.org/show_bug.cgi?id=676133
https://bugzilla.gnome.org/show_bug.cgi?id=674658
giscanner: move AnnotationParser() warning tests

The following patch (add support for deprecated @Varargs
parameter notation) would require adding a new expected
warning to tests/warn/unknown-parameter.h before all
other warnings, even those from unrelated comment blocks.
This because AnnotationParser() warnings are emitted *before*
MainTransformer() warnings.

This patch extracts all warning tests related to AnnotationParser()
into the test_parser.py testsuite instead.
giscanner: add support for deprecated @Varargs parameter notation

Transparently transform @Varargs into @... and add tests.
giscanner: fix Attributes: tag transformation into (attributes) annotation
giscanner: deprecate (attribute) annotation...

...and replace it with (attributes). This allows
for multiple key/value pairs to be annotated with
the (attributes key1=value2 key2 key3=value2) notation
instead of a single (attribute key value)...
giscanner: handle deprecated angled brackets in deprecated "Type:", "(type)" and (element-type)
giscanner: always store DocTag.comment, drop DocTag.value usage
giscanner: fix erronous "missing ':'" warnings
giscanner: improve wording of inline documentation
giscanner: refactoring: rename colon to delimiter