[gobject-introspection] docs: document some annotationparser.py hacking hints

[Colin Walters <walters src gnome org>]

commit 9ba1fc2cadb4da883487f9262adc7a4f771cc249
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date:   Sat May 4 00:52:12 2013 +0200

    docs: document some annotationparser.py hacking hints
    
    https://bugzilla.gnome.org/show_bug.cgi?id=688897

 HACKING                               |   41 ++++++++++++++++++++++++++++++--
 tests/scanner/annotationparser/README |   22 +++++++++---------
 2 files changed, 49 insertions(+), 14 deletions(-)
---
diff --git a/HACKING b/HACKING
index 0c2ea14..f951205 100644
--- a/HACKING
+++ b/HACKING
@@ -1,9 +1,44 @@
 Notes to developers hacking on GObjectIntrospection
+===================================================
+
+
+debugging
+---------
 
 * You can use the GI_SCANNER_DEBUG environment variable; see utils.py
   for a list of debug flags.
 
-* If you add a new warning, you should add a new test for it
-  in test/warn
 
-* Before pushing code to the repository, make sure to run make check
+giscanner
+---------
+
+* If you add a new warning to annotationparser.py, you should add new
+  tests for it in tests/scanner/annotationparser/gi/
+
+* If you add a new warning elsewhere (maintransformer.py, etc), you
+  should add a new test for it in tests/warn/
+
+* Before pushing code to the repository, make sure to run 'make check' or
+  even 'make distcheck'
+
+* While hacking on annotationparser.py it is a good idea to:
+    1) Update your GLib build to git master.
+    2) Run the following command from your gobject-introspection source directory before making
+       changes to annotationparser.py (adapt GLib source and/or build directory as required):
+       (cd misc && ./update-glib-annotations.py /path/to/gnome.org/checkout/glib/)
+    3) Ensure changes to the following files are as expected, meaning they are caused by
+       updated GLib annotations and not by stray modifications to annotationparser.py:
+         - gir/gio-2.0.c
+         - gir/glib-2.0.c
+         - gir/gobject-2.0.c
+       When satisfied, commit these files adding "Update GLib annotations to master" as the
+       commit message.
+    4) Only now start editing annotationparser.py.
+    5) run make check.
+    6) Run update-glib-annotations.py again and carefully study the changes (if any) to:
+         - gir/gio-2.0.c
+         - gir/glib-2.0.c
+         - gir/gobject-2.0.c
+       Ensure changes in these files are as intended and caused by the modifications done to
+       annotationparser.py. Commit the changes to annotationparser.py and the above
+       files as a single patch.
diff --git a/tests/scanner/annotationparser/README b/tests/scanner/annotationparser/README
index 236671e..1dbc64e 100644
--- a/tests/scanner/annotationparser/README
+++ b/tests/scanner/annotationparser/README
@@ -15,31 +15,31 @@ test_parser.py
 Notes
 -----
 
-- the names of directories containing test .xml and the .xml files themselves should
+- the names of the 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
+- GTK-Doc comment blocks can contain XML (DocBook) 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
+  Occasionally, GTK-Doc comment blocks containing XML (DocBook) 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!
+- *Note well* that trailing whitespace characters in test .xml files are not there by accident.
+  So whatever your text editor of choice or scm du jour might claim, trailing whitespace
+  is required!
 
 
-Tests
------
+Test files
+----------
 
 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.
+  GtkDocCommentBlockParser 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
@@ -47,6 +47,6 @@ gtk-doc/*.xml:
     - updated 2013/07/30 to 1846fc7e904f6f56b74c366d205d6bb946eac17e
 
 gobject-introspection/*.xml:
-  GTK-Doc comment blocks specifically designed to ensure AnnotationParser does the
+  GTK-Doc comment blocks specifically designed to ensure GtkDocCommentBlockParser 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).