[gtk-doc] scan: provide a way to skip unparsable code

[Stefan Kost <stefkost src gnome org>]

commit 2ae6867592017bb83b39c3be201e842cf77fc1f7
Author: Stefan Kost <ensonic users sf net>
Date:   Mon Sep 13 14:14:08 2010 +0300

    scan: provide a way to skip unparsable code
    
    Allow to use #ifndef __GTK_DOC_IGNORE__ to mark unparseable code.
    Fixes #512565.

 gtkdoc-scan.in                   |   16 ++++++++++++++++
 help/manual/C/gtk-doc-manual.xml |   15 +++++++++++++++
 tests/bugs/src/tester.h          |    3 +++
 3 files changed, 34 insertions(+), 0 deletions(-)
---
diff --git a/gtkdoc-scan.in b/gtkdoc-scan.in
index 95b9746..da1111d 100755
--- a/gtkdoc-scan.in
+++ b/gtkdoc-scan.in
@@ -277,6 +277,7 @@ sub ScanHeader {
     my $file_basename;
 
     my $deprecated_conditional_nest = 0;
+    my $ignore_conditional_nest = 0;
 
     my $deprecated = "";
 
@@ -332,14 +333,25 @@ sub ScanHeader {
             } elsif ($deprecated_conditional_nest > 0) {
                  $deprecated_conditional_nest += 1;
             }
+            if ($ignore_conditional_nest == 0 and $1 =~ /__GTK_DOC_IGNORE__/) {
+                 $ignore_conditional_nest = 1;
+            } elsif ($ignore_conditional_nest > 0) {
+                 $ignore_conditional_nest += 1;
+            }
         } elsif (m/^\s*#\sif/) {
             if ($deprecated_conditional_nest > 0) {
                  $deprecated_conditional_nest += 1;
             }
+            if ($ignore_conditional_nest > 0) {
+                 $ignore_conditional_nest += 1;
+            }
         } elsif (m/^\s*#endif/) {
             if ($deprecated_conditional_nest > 0) {
                 $deprecated_conditional_nest -= 1;
             }
+            if ($ignore_conditional_nest > 0) {
+                $ignore_conditional_nest -= 1;
+            }
         }
 
         # set global that affects AddSymbolToList
@@ -348,6 +360,10 @@ sub ScanHeader {
         } else {
             $deprecated = "";
         }
+        
+        if($ignore_conditional_nest) {
+            next;
+        }
 
 	if (!$in_declaration) {
 	    # Skip top-level comments.
diff --git a/help/manual/C/gtk-doc-manual.xml b/help/manual/C/gtk-doc-manual.xml
index 2217edf..bb3329b 100644
--- a/help/manual/C/gtk-doc-manual.xml
+++ b/help/manual/C/gtk-doc-manual.xml
@@ -614,6 +614,21 @@ make
 	way of documenting code.
       </para>
     </note>
+    
+    <para>
+      The scanner can handle the majority of c headers fine. In the case of
+      receiving warnings from the scanner that look like a special case, one can
+      hint GTK-Doc to skip over them.
+      <example><title>GTK-Doc comment block</title>
+        <programlisting>
+<![CDATA[
+#ifndef __GTK_DOC_IGNORE__
+/* unparseable code here */
+#endif
+]]>
+        </programlisting>
+      </example>
+    </para>
 
     <!--  -->
 
diff --git a/tests/bugs/src/tester.h b/tests/bugs/src/tester.h
index 1a900d7..065c60a 100644
--- a/tests/bugs/src/tester.h
+++ b/tests/bugs/src/tester.h
@@ -329,6 +329,9 @@ const char ** const bug_624200b(void);
 gchar *_bug_000000a (const gchar *name);
 #define _BUG_000000b (a) (a*a);
 
+#ifndef __GTK_DOC_IGNORE__
+extern int bug_512565(void);
+#endif
 
 #endif // GTKDOC_TESTER_H