giscanner: add AnnotationParser tests

The tests in giscanner/annotationpatters.py only test the regular
expression programs used when parsing GTK-Doc comment blocks but
do not test the structure of the resulting "parse tree".

This patch adds 193 GTK-Doc comment blocks and the expected
results AnnotationParser should return (with it's current level
of understanding of GTK-Doc comment block syntax). These are
compared by tests/scanner/annotationparser/test_parser.py which
complains with a diff on failure.

https://bugzilla.gnome.org/show_bug.cgi?id=688897

1 files changed, 40 insertions, 0 deletions

diff --git a/tests/scanner/annotationparser/README b/tests/scanner/annotationparser/README
new file mode 100644
index 00000000..1f621a57
--- /dev/null
+++ b/tests/scanner/annotationparser/README
@@ -0,0 +1,40 @@
+test_parser.py
+==============
+
+Notes
+-----
+
+- the names of directories containing test .xml and the .xml files themselves should
+  not contain the hyphen ('-') character. This because we use the directory and file
+  names to generate valid Python method names (where the hyphen character is illegal).
+
+- GTK-Doc comment blocks can contain XML fragments on their own. You can wrap such
+  comment blocks into a CDATA section to prevent the tests XML parser from doing the
+  wrong thing.
+  Occasionally, GTK-Doc comment blocks containing XML fragments can also contain CDATA
+  sections on their own. This can be handled by wrapping the GTK-Doc comment block into
+  a CDATA section as described above, and escape the embedded GTK-Doc CDATA section's
+  opening bracket "<!" with "{{!" and the matching close bracket ">" with "!}}".
+
+- *Note well* that the trailing whitespace in gi/syntax_paragraph_breaks.xml *is* expected.
+  Whatever your text editor of choice or scm du jour might claim, trailing whitespace
+  are required for these tests!
+
+
+Tests
+-----
+
+gtk-doc/*.xml:
+  The GTK-Doc comment block tests in this directory are copied verbatim from the GTK-Doc
+  test suite. Not all of these tests make sense from GTK-Doc's point of view without the
+  actual C sources they document, but are great for testing the level of understanding
+  AnnotationParser has about the GTK-Doc comment block syntax.
+
+  GTK-Doc tests originally taken at revision:
+  http://git.gnome.org/browse/gtk-doc/tree/tests?id=2a6b01253fe41412172a60f26705114b953d0a95
+
+
+gobject-introspection/*.xml:
+  GTK-Doc comment blocks specifically designed to ensure AnnotationParser does the
+  right thing and continues to function correctly. The goal is to exercise all possible
+  combinations of tags, parameters and annotations (both current and deprecated syntax).