added version check against gcc-generated xml; added readme and few other notes about ifacecheck

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53534 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/doxygen/mainpages/utilities.h

@@ -71,6 +71,9 @@ can even correct them automatically. It uses the XML outputs of the gccxml utili
 (see http://www.gccxml.org) and of the Doxygen utility (see http://www.doxygen.org)
 to do the comparisons.
 
+It's explicitely designed for wxWidgets documentation needs and is probably of little
+use for anything else than wxWidgets docs reviewing.
+
 You can find it in @c utils/ifacecheck.
 
 

utils/ifacecheck/README

@@ -0,0 +1,55 @@
+
+ Ifacecheck utility
+ ==================
+
+ 1) INTRODUCTION
+
+ This utility compares the wxWidgets real interface contained in the "include"
+ hierarchy with the wxWidgets interface used for documentation purposes and
+ kept in the @c interface hierarchy.
+
+ Ifacecheck warns about incoherences (mainly wrong prototype signatures) and
+ can even correct them automatically. It uses the XML outputs of the gccxml utility
+ (see http://www.gccxml.org) and of the Doxygen utility (see http://www.doxygen.org)
+ to do the comparisons.
+
+ It's explicitely designed for wxWidgets documentation needs and is probably of little
+ use for anything else than wxWidgets docs reviewing.
+
+
+ 2) PREREQUISITES FOR USING IT
+
+ To use this utility you'll need at least:
+  - wxWidgets "include" and "interface" headers tree
+  - Doxygen installed
+  - Gccxml installed
+
+
+ 3) HOW TO USE IT (on Linux)
+
+    First, create the doxygen XML:
+
+     > cd docs/doxygen
+     > ./regen.sh xml
+     > cd ../..
+
+    Next, create the gcc XML:
+
+     > ./configure                # configure wxWidgets as you would do when building it
+     > cd utils/ifacecheck
+     > ./rungccxml.sh
+     > cd ../..
+
+    Last, build and run ifacecheck:
+
+     > cd utils/ifacecheck/src
+     > make
+     > make install
+     > cd ..
+     > ifacecheck -u wxapi-preproc.txt wxapi.xml ../../docs/doxygen/out/xml/index.xml >ifacecheck.log
+
+    Now you should have the log of the utility saved in 'ifacecheck.log'.
+    Its contents should be easy to interpret.
+
+    For more info about ifacecheck options just type:
+     > ifacecheck --help

utils/ifacecheck/src/xmlparser.cpp

@@ -563,6 +563,31 @@ bool wxXmlGccInterface::Parse(const wxString& filename)
         return false;
     }
 
+    wxString version = doc.GetRoot()->GetAttribute("cvs_revision");
+    bool old = false;
+
+#define MIN_REVISION  120
+
+    if (!version.StartsWith("1."))
+        old = true;
+    if (!old)
+    {
+        unsigned long rev = 0;
+        if (!version.Mid(2).ToULong(&rev))
+            old = true;
+        else
+            if (rev < MIN_REVISION)
+                old = true;
+    }
+
+    if (old)
+    {
+        LogError("The version of GCC-XML used for the creation of %s is too old; "
+                 "the cvs_revision attribute of the root node reports '%s', "
+                 "minimal required is 1.%d.", filename, version, MIN_REVISION);
+        return false;
+    }
+
     wxToResolveTypeHashMap toResolveTypes;
     wxClassMemberIdHashMap members;
     wxTypeIdHashMap types;
@@ -1076,6 +1101,13 @@ bool wxXmlDoxygenInterface::Parse(const wxString& filename)
         return false;
     }
 
+    /*
+        NB: we may need in future to do a version-check here if the
+            format of the XML generated by doxygen changes.
+            For now (doxygen version 1.5.5), this check is not required
+            since AFAIK the XML format never changed since it was introduced.
+    */
+
     m_classes.Alloc(ESTIMATED_NUM_CLASSES);
 
     // process files referenced by this index file