diff options
Diffstat (limited to 'tests/scanner/annotationparser/README')
| -rw-r--r-- | tests/scanner/annotationparser/README | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/tests/scanner/annotationparser/README b/tests/scanner/annotationparser/README new file mode 100644 index 00000000..03cdf59d --- /dev/null +++ b/tests/scanner/annotationparser/README @@ -0,0 +1,51 @@ +test_patterns.py +================ + +Notes +----- + +The tests included within test_patterns.py are designed to torture the regular +expression programs used to match different parts of GTK-Doc comment blocks +by giscanner/annotationparser.py + + +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). |