giscanner: small py3k fixes

Note that this does not mean g-i will start supporting Python 3.x,
only that as a future-proofing exercise, the annotationparser work
that is about to land has been tested (test_patterns.py and
test_parser.py) with Python 2.7 and 3.2.
giscanner: improve wording of inline documentation
giscanner: use "if in [a, b]" instead of "if == a or if == b"
giscanner: make it clear DocOptions() also has a position attribute

Lost a couple of hours hunting down a failed test case (from the
annotationparser work about to land) due to this not being clear...
giscanner: use re.match() instead of re.search()

From Python's documentation:
Python offers two different primitive operations based on
regular expressions: match checks for a match only at the
beginning of the string, while search checks for a match
anywhere in the string (this is what Perl does by default).

The different behavior between match() and search() doesn't
matter in our case and conceptually we are checking if a
piece of text matches a certain pattern, so match() is a
better fit.
giscanner: deprecate top level g-i specific GTK-Doc tags.

Much is going on in this patch that cannot be represented in
smaller patches without either loosing meaning or breaking git
bisect. Apologies to the unfotunate reviewer(s)!

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 unforseen side
effect reported in bug http://bugzilla.gnome.org/show_bug.cgi?id=674658.

Analysing this problem we found that even though comment blocks
having g-i specific tags before the comment block description
are technically malformed, g-i specific tags never have a multiline
description to begin with. 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 comment blocks did not result in the expected html
output. All hell broke loose...

In short, we learned that these g-i specific top level tags should
never have existed in the first place, preferring annotations on the
identifier instead. As a result, this patch deprecates g-i specific
top level tags and implements them as annotations on the identifier
instead. Without breaking support for malformed comment blocks still
using g-i specific top level tags.

This means that all annotated code "out there" should 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 at least version 1.33.3.

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

1) TAG_RE: due to the realisation that the list of top level tags is
   basically frozen, TAG_RE now only accepts know tag names. These
   names are however defined in giscanner/annotationparser.py. To
   prevent a circular import, all regular expression programs from
   giscanner/annotationpatterns.py are moved into
   giscanner/annotationparser.py. The left over tests are moved into
   tests/giscanner/annotationparser/test_patters.py resulting in the
   complete removal of giscanner/annotationpatterns.py

2) before attempting to deprecate g-i specific top level tags, tests
   have been written ensuring both old and new style comment blocks
   continue to be parsed correctly. This is ensured by
      tests/giscanner/annotationparser/test_parser.py
      tests/giscanner/annotationparser/gtkdoc/*.xml
      tests/giscanner/annotationparser/gi/*.xml
   and is documented in
      tests/giscanner/annotationparser/README

3) 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 new (attributes) annotation
   counterpart continue to be broken (regression introduced in
   commit 182fdfec261f36fa095484352b9b834861036907), which will be
   addressed in a followup patch.

4) comment blocks in tests/*.c and tests/*.h had to be adjusted as
   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.

This hopefully satisfies https://bugzilla.gnome.org/show_bug.cgi?id=676133
while fixing http://bugzilla.gnome.org/show_bug.cgi?id=674658.
Update GLib annotations to master

Which at the time of writing is GLib commit 08cfcdc81add6f6f2247b1cc82d2c15ad27001f0
giscanner: Fix annotations pattern

The "annotations" part of our regular expression programs failed
on multiple closing parentheses like (element-type GLib.List(utf8)).
This patch adds tests and fixes the issue.

Thanks to Colin Walters for the scrutiny and voicing his concerns on irc!