README
1test_patterns.py
2================
3
4Notes
5-----
6
7The tests included within test_patterns.py are designed to torture the regular
8expression programs used to match different parts of GTK-Doc comment blocks
9by giscanner/annotationparser.py
10
11
12test_parser.py
13==============
14
15Notes
16-----
17
18- the names of the directories containing test .xml and the .xml files themselves should
19 not contain the hyphen ('-') character. This because we use the directory and file
20 names to generate valid Python method names (where the hyphen character is illegal).
21
22- GTK-Doc comment blocks can contain XML (DocBook) fragments on their own. You can wrap such
23 comment blocks into a CDATA section to prevent the tests XML parser from doing the
24 wrong thing.
25 Occasionally, GTK-Doc comment blocks containing XML (DocBook) fragments can also contain
26 CDATA sections on their own. This can be handled by wrapping the GTK-Doc comment block into
27 a CDATA section as described above, and escape the embedded GTK-Doc CDATA section's
28 opening bracket "<!" with "{{!" and the matching close bracket ">" with "!}}".
29
30- *Note well* that trailing whitespace characters in test .xml files are not there by accident.
31 So whatever your text editor of choice or scm du jour might claim, trailing whitespace
32 is required!
33
34
35Test files
36----------
37
38gtk-doc/*.xml:
39 The GTK-Doc comment block tests in this directory are copied verbatim from the GTK-Doc
40 test suite. Not all of these tests make sense from GTK-Doc's point of view without the
41 actual C sources they document, but are great for testing the level of understanding
42 GtkDocCommentBlockParser has about the GTK-Doc comment block syntax.
43
44 GTK-Doc tests originally taken at revision:
45 http://git.gnome.org/browse/gtk-doc/tree/tests?id=2a6b01253fe41412172a60f26705114b953d0a95
46 and should be updated regularly to reflect changes in the GTK-Doc project.
47
48gobject-introspection/*.xml:
49 GTK-Doc comment blocks specifically designed to ensure GtkDocCommentBlockParser does the
50 right thing and continues to function correctly. The goal is to exercise all possible
51 combinations of tags, parameters and annotations (both current and deprecated syntax).
52