tests: Update misc/pep8.py to 1.4.5

Old version in our tree does not understand utf8 encoded python
source files, effectively miscounting line numbers on utf8 characters.
We'll need that later on so update pep8.py from:
https://raw.github.com/jcrocholl/pep8/1.4.5/pep8.py

Takes 552c1f1525e37a30376790151c1ba437776682c5,
f941537d1c0a40f0906490ed160db6c79af572d3,
5a4afe2a77d0ff7d9fea13dd93c3304a6ca993de and
a17f157e19bd6792c00321c8020dca5e5a281f45 into account...
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
Add a tool fixing GTK-Doc comment blocks in .c and .h files

Just a standalone script for now, should probably eventually
go into g-ir-doctool or g-ir-annotation-tool...
giscanner: don't calculate absolute path twice for the same filenames

This is already being done in the first filenames loop...
giscanner: Define source and header filename extensions only once

Enables us to to use a more effecient list membership test
instead of testing the end of some string multiple times.
giscanner: small cpp_args cleanup

No need for two variables...
[WIP] docs: improve layout
!!! for testing only !!!
win32: open files in binary mode

Opening files in text mode can have funny side effects, for example
passtrough_gir() can file because the C runtime change a \n to \r\n
behind our backs etc...
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
build: silence "make[5]: unlink: Regress-1.0-Python: Is a directory"
build: make it clear generated documentation goes in $(builddir)
build: use diff -r when testing generated docs
Add generated Visual Studio project file stuff to .gitignore